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^  REPORT  SUMMARY 

/ 


This  report  covers  technical  development  at  UCLA  relating  to  the 
National  Software  Works  (NSW)  during  1978.  It  is  a  combination  of  the 
two  Semi-annual  Technical  Reports  covering  the  periods  of  January  1 
throng  June  30  and  July  1  through  Deceodber  31  of  1978. 

The  primary  goal  of  the  NSW  project  at  UCLA  is  to  make  the  IBM  Operating 
System  OS/MVT,  and  specifically  its  Isplementation  on  the  UCLA  IBM 
360/91,  a  "tool -bearing  host”  within  the  NSW.  This  report  is 
specifically  concerned  with  the  design  and  Isiplementatlon  of  the  NSW 
File  Package  component  under  OS/MVT.  The  next  three  sections  of  the 
report  correspond  to  specific  documents  stored  in  the  NSW  documentation 
repository  maintained  by  the  NSW  Operations  Contractor,  so  each  section 
has  been  made  self-ccmtained.  For  exas^le,  each  section  has  its  own 
table  of  contents  and  reference  sumsMry,  and  each  section  is 
independently  paginated. 

Part  II:  FP/360  —  The  NSW  MVT  File  Package 

This  section  describes  FP/360,  the  File  Package  iBq>lementatlon  for 
OS/MVT,  from  the  aspect  of  its  use  as  an  NSW  core-system 
coogxment.  It  does  not  go  into  program  logic  to  any  depth. 

Part  III:  The  NSW  Basic  Copy  Machine 

This  section  describes  that  subcomponent  of  FP/360  called  the 
"Basic  Copy  Machine",  or  BCM.  The  BCM  can  be  viewed  as  a 
separable  piece  of  software  that  performs  a  generalized  data  copy 
operation  according  to  parameters  set  up  and  pre-validated  by  the 
File  Package  proper.  The  separation  of  function  is  not  cooiplete, 
particularly  in  the  area  of  Network  interface.  Nevertheless,  it 
serves  the  purpose  of  breaking  the  rather  massive  File  Package 
down  into  two  more  easily  described  parts. 

Part  IV:  UCLA  Reccommendations  on  Libraries  in  NSW 


This  section  presents  UCLA's  observations  and  reccommendations  on 
a  fundamental  problem  that  must  be  solved  before  NSW  can 
adequately  support  the  use  of  IBM-compatible  software  tools.  The 
NSW  file  system,  and  thus  FP/360,  supports  only  sequential  files, 
while  most  IBM  program-development  tools  make  generous  use  of 
"partitioned",  or  library,  files.  So  under  present 
specifications,  FP/360  is  not  capable  of  supporting  IBM  tools  in 
NSW. 


FP/360 
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2.  PART  II:  FP/360 


2.1.  FP/360  FUNCTIONAL  SPECIFICATIONS 

Within  the  National  Software  Works  (NSW),  each  Tool-bearing  host  (TBH) 
is  required  to  have  a  software  component  called  a  "File  Package"  or 
"FP",  for  moving  and  converting  files.  This  document  describes 
FP/360,  a  File  Package  Implementation  for  the  IBM  360.  Specifically, 
FP/360  was  developed  to  operate  on  the  UCLA  IBM  System/360  model  91KK 
under  the  MVT  Operating  System  with  the  Time-Sharing  Option,  TSO  (we 
commonly  refer  to  this  system  as  OS/MVT).  However,  with  the 
replacement  of  certain  installation  -  dependent  modules,  it  will 
operate  on  any  upward  -  compatible  system. 

The  reader  is  assumed  to  be  familiar  with  reference  1,  which 
prescribes  the  operation  and  protocols  of  an  NSW  File  Package,  and 
with  the  software  environment  provided  by  the  NSW. 

FP/360  communicates  with  other  NSW  processes  via  the  NSW  Network 
Transaction  Protocol,  or  NTP  (reference  2,  appendix  3),  On  an  IBM 
system,  NTP  is  implemented  on  three  levels: 

*  The  procedure-call  level  is  Implemented  by  the  PL/PCP  subroutine 
package  (reference  3). 

*  The  MSG  message  and  direct -connect ion  level  is  implemented  by  the 
PL/MSG  subroutine  package  (reference  4),  which  also  uses  the  PLOXI 
package  (reference  7). 

*  The  NSWB8  data  encodement  level  is  handled  by  the  PL/B8  subroutine 
package  (reference  5). 

This  document  describes  in  particular  Version  2  of  the  FP/360 
imp lement at ion . 
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2.1.1.  OVERVIEW 

FP/360  functions  as  an  NSV  core*system  process  with  generic  name 
"FLPKG”.  It  Is  essentially  a  file-copying  machine  responding  to  a 
well-defined  set  of  procedure  calls  In  a  well-defined  way.  Each 
operation  which  can  be  performed  by  FP/360  is  Invoked  by  a  single 
NTP  transaction  of  the  form:  Generlc-request/Specific-reply.  Such 
a  transaction,  a  "procedure  call"  on  an  FP  procedure,  can  be 
expressed  in  the  form: 

procedurename  (argument -list)  ->  (result-list) 

In  particular,  FP/360  can  execute  a  procedure  call  from  these  remote 

processes : 

2. 1.1.1.  From  a  remote  process  of  class  "VM"  (Works  Manager)  or  "WHO" 
(Works  Manager  Operator)  FP/360  can  execute  a  call  to  one  of  these 
procedure  names: 

*  FP-EXP  (the  "Export"  procedure  call) 

*  FP-IMP  (the  "Import"  procedure  call) 

*  FP-TRANS  (the  "Transport"  procedure  call) 

These  three  procedures,  collectively  called  the  "GET  procedures", 
are  all  concerned  with  producing  a  local  disk  data  set  filled  with 
the  data  records  of  a  given  file.  The  source  may  be  either  a 
local  data  set  or  a  remote  FP,  l.e.,  an  FP  on  another  host.  To 
retrieve  a  file  across  the  ARPANET,  the  local  FP  contacts  an  FP 
Instance  on  the  donor  host  by  Issuing  a  subsidiary  (FP-SENDME) 
procedure  call  for  the  latter.  The  two  FP's  then  open  a  binary 
simplex  connection  to  pass  the  data. 

The  source  data  may  be  encoded  in  IL  (Intermediate  Language,  see 
Appendix  D)  or  it  may  be  in  "clear  text",  l.e.,  in  one  of  the  many 
standard  disk  formats  supported  by  the  local  operating  system, 
OS/MVT.  The  output  data  set  is  to  have  specified  well-defined 
local  file  attributes,  but  the  input  data  may  or  may  not  carry 
these  or  compatible  attributes.  The  GET  procedures  are  the  most 
complex  parts  of  FP/360,  as  the  full  range  of  data  conversions  may 
be  needed. 

2. 1.1.2.  From  a  remote  process  of  class  "CHKPTR"  (Checkpointer) ,  "VM",  or 

"who",  FP/360  can  execute  a  call  to  the  procedure  name: 


*  FP-DEL  (the  "Delete"  procedure  call) 
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This  procedure  deletes  a  physical  copy  from  the  local  disk  space 
(which  implies  removing  its  name  from  the  local  file  directory 
■wchanlsm) . 

From  a  remote  process  of  class  "FLPKG"  (another  File  Package) 
FP/360  can  execute  a  call  to  the  procedure  name: 

*  FP-SENDME  (the  "SendMe”  procedure  call) 

This  procedure  copies  a  file  from  a  local  disk  data  set  to  a 
remote  FP  through  a  binary  direct  connection.  The  data  will  be 
encoded  into  IL,  and  all  local  file-type  dependencies  will  be 
stripped  from  the  data;  however,  no  real  data  conversion  is 
required. 

The  following  call  is  defined,  but  is  not  presently  used  by  any 
NSW  process;  it  is  a  no-operation  in  FP/360: 

*  FP-ANAL  (the  "Analyze"  procedure  call) 


Later  sections  will  describe  each  of  these  operations,  with  their 
parameters  and  results.  If  any  argument  list  contains  more 
arguments  than  are  known  to  the  selected  executor,  the  excess  is 
discarded  without  comment.  If  extensions  are  defined  in  an 
upward-compatible  way,  this  feature  will  prove  useful. 

When  it  is  started,  FP/360  materializes  as  an  MSG  process  and  issues 
a  ReceiveGenerlc  for  a  generic  class  determined  by  an  Initialization 
procedure  (normally  "FLPKG").  When  the  receive  completes,  FP/360 
processes  the  request  for  its  caller.  For  a  GET  call,  the  local  FP 
may  in  turn  issue  a  SendHe  call  to  a  remote  FP.  While  processing  a 
call,  FP/360  is  not  enabled  for  new  generic  calls,  and  will  reject 
any  specifically  addressed  messages  from  any  process  other  than  its 
caller  or  its  current  callee,  by  sending  an  NTP  reply  with  null 
results  and  a  standard  rejection  error  descriptor. 

When  it  has  completed  processing,  FP/360  returns  an  NTP  reply 
message  to  the  original  caller,  and  then  rematerializes  as  a  new 
process  instance,  thus  becoming  once  again  receptive  to  generic 
calls.  It  continues  to  recycle  in  this  manner  until  a  fixed  count 
of  cycles,  included  in  the  initialization  parameters,  is  exceeded. 


Supporting  the  IBM  File  System  in  NSW 
November  20,  1980  —  Part  II:  FP/360 

PAGE  4 


PARAMETRIC  DATA  STRUCTURES 

Every  call  on  an  FP  procedure  includes  a  set  of  parameters  encoded 
in  an  NSVB8  LIST  (reference  5).  While  the  parameter  structure  of 
the  call  is  peculiar  to  its  procedure,  many  of  the  elements  of  that 
structure  are  commonly  defined.  This  section  gives  FP/360 's 
interpretation  of  these  common  elements. 

PCD  --  PHYSICAL  COPY  DESCRIPTOR 

For  each  physical  copy  of  an  NSW  file,  the  Works  Manager  keeps  a 

"Physical  Copy  Descriptor"  (PCD)  in  its  file  catalog.  A  PCD  is 

used  by  FP/360  in  one  of  four  different  ways: 

1)  The  Works  Manager  passes  FP/360  a  PCD  as  the  definition  of 
the  location  and  IL-encodement  of  an  existing  physical  copy 
of  an  NSW  file,  or  an  existing  data  set  outside  NSW  file 
space. 

2)  The  Works  Manager  passes  FP/360  a  partially  filled  PCD  to 
identify  the  directory  and/or  name  under  which  a  new  data 
set  is  to  be  created;  this  is  called  a  "skeleton  PCD". 

3)  FP/360  passes  the  Works  Manager  a  PCD  to  define  the  location 
and  IL~encodement  of  a  newly  created  data  set. 

4)  FP/360  passes  the  Works  Manager  a  null  PCD  as  notice  that  a 
data  set  was  not  created  (a  null  PCD  consists  of  a  NSWB8 
LIST  of  count  0). 

FP/ interprets  the  fields  of  the  PCD  as  follows: 

*  HOST 

The  HOST  field  is  an  NSW  host  number.  This  field  is  only  of 
interest  when  the  PCD  is  being  used  to  locate  an  existing  data 
set.  FP/360  uses  a  PL/MSG  function  (reference  3)  to  classify 
the  host  as  LOCAL,  FAMILY,  or  FOREIGN.  If  HOST  is  not  LOCAL, 
then  only  two  interpretations  of  PCD  data  are  possible:  1)  the 
host  number  can  be  used  in  a  SendMe  call  to  another  File 
Package;  and  2)  the  ILFLAG  field  (see  below)  can  be  examined. 

*  DIRECTORY 

The  DIRECTORY  field  for  a  local  data  set  is  always  chosen  by 
some  process  on  the  local  host,  and  it  is  generally  an 
uninterpretable  character  string  for  remote  FP's.  When  the  WM 
calls  FP/360  to  make  a  tool  copy  of  a  file,  the  call  includes 
the  tool -workspace  directory  chosen  by  the  local  Foreman.  In 
other  cases  of  making  a  local  copy,  the  local  FP  should  be 
allowed  to  choose  the  directory,  so  the  PCD  DIRECTORY  field 


‘.t  »>«  'll ' 
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should  be  null. 

For  a  local  360  file,  DIRECTORY  contains  that  part  of  the  local 
data  set  name  that  corresponds  to  an  MVT/TSO  LOGON  directory. 
The  Interpretation  of  a  TSO  LOGON  directory  may  vary  from  one 
360  installation  to  another.  At  UCLA,  the  DIRECTORY  Field  will 
contain  a  character  string  of  the  form  "cccccc . uuu” ,  where 
"cccccc"  is  a  CCN  charge  number  and  ''uuu'*  is  the  TSO  "userid". 

L0G(M  directories  with  the  same  account  number  form  a  "group", 
and  the  directory  used  to  run  a  job  can  have  group-wide  access. 
Version  2  of  FP/360  will  have  no  mechanism  to  access  files 
outside  the  directory  group  in  which  it  was  started. 
Fortunately,  it  is  anticipated  that  all  NSV-related  file 
directories  will  be  in  the  same  group. 

If  a  skeleton  PCD  has  a  null  DIRECTORY  field  or  is  completely 
null,  then  FP/360  will  use  one  of  '  two  default  directories 
specified  by  the  initialization  parameters:  NSW  filespace 
default,  or  non-NSW  filespace  default. 

NAME 

The  NAME  field  contains  that  part  of  the  locals  file  name  (called 
a  "data  set  name"  in  MVT)  that  is  not  contained  in  DIRECTORY. 
An  MVT  data  set  name  (DSNAME)  is  formed  by  catenating  these  two 
fields  with  a  period  between  them. 

FP/360  will  accept  "wild"  characters  (question  marks)  in  a  NAME 
field,  and  will  generate  pseudo-random  substitutions  to  create  a 
unique  local  name.  If  a  PCD  which  is  required  to  specify  the 
name  for  creating  a  new  data  set  contains  a  null  NAME  string,  or 
is  entirely  null,  FP/360  will  use  a  default  name  from  its 
initialization  parameters.  Again,  there  are  two  defaults,  one 
for  NSW  and  one  for  non-NSW  file  space.  The  default  names  will 
generally  contain  wild  characters. 

PHYS 

The  PHYS  field  is  never  examined  by  FP/360  (see  the  section 
entitled  "NSW  FILE  ATTRIBUTES",  below).  In  PCD's  generated  by 
FP/360,  it  will  be  a  character  string  of  count  0. 

ILFLAG 

The  ILFLAG  field  is  a  Boolean  value  which  means  "this  data  set 
is  already  physically  encoded  in  IL".  FP/360  will  use  this 
datum  when  ranking  a  set  of  donor  file  candidates  in  a  GET 
procedure . 
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When  the  PCD  is  defining  a  new  data  set  to  the  Works  Manager, 
this  is  the  only  place  where  IL~encodement  is  recorded. 
Consequently,  when  the  PCD  is  for  an  existing  data  set  on  the 
LOCAL  host,  this  datum  is  the  only  one  that  can  tell  FP/360 
whether  the  data  is  already  IL-encoded. 

2. 1.2.2.  PASSWORD 

The  NSW  PASSWORD  parameter  is  treated  differently  depending  on  the 
corresponding  data  set's  location: 

*  If  the  data  set  is  not  on  the  local  host,  then  the 

interpretation  of  the  password  is  the  responsibility  of  another 
File  Package.  If  FP/360  issues  a  SendMe  call  to  that  File 

Package,  the  password  used  in  that  call  will  be  a  copy  of  the 

one  that  FP/360  received  from  the  Works  Manager. 

*  If  the  data  set  is  locally  resident,  then  the  password  is 

intended  for  gaining  access  to  the  specified  local  directory. 
However,  as  noted  previously.  Version  2  does  not  allow  access  to 
directories  which  would  require  passwords  (i.e.,  those  in  a 
group  different  from  the  one  in  which  FP/360  is  running),  so  the 
password  is  Ignored.  , 

2. 1.2.3.  GFT  —  GLOBAL  FILE  TTPE 

The  NSW  Global  File  Type  (GFT)  is  the  symbolic  name  for  a 
particular  set  of  file  attributes.  It  has  the  form: 

'<host  famlly>-<flle  type>' 

When  <host  famlly>  is  *360',  the  GFT  is  said  to  be  "native"  to  an 
IBM  360  and  hence  to  FP/360.  The  File  Package  on  each  host  family 
srast  know  all  the  attributes  associated  with  every  native  GFT; 
however,  it  need  not  (and  must  not)  assume  an3rthing  about  the 
attributes  associated  with  a  non-native  GFT. 


In  particular,  FP/360  includes  a  table  containing  the  Global  File 
Attributes  (GFA's),  Local  File  Attributes  (LFA's)  and  default 
Physical  Structure  Attributes  (PSA's)  for  every  native  GFT.  If  a 
native  GFT  passed  to  FP/360  does  not  appear  in  this  table,  then  a 
system  inconsistency  exists,  and  appropriate  local  error  logging 
will  occur. 

2. 1.2. 4.  GFD  —  GLOBAL  FILE  DESCRIPTOR 

The  NSW  Global  File  Descriptor  (GFD)  is  used  by  FP/360  to  define 
the  Global  File  Attributes  (GFA's)  of  an  NSW  file  with  a 
non-native  file  type.  Thus,  when  FP/360  receives  a  GFT  from  the 
Works  Manager,  there  are  two  cases: 
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*  If  the  GET  does  not  begin  with  the  characters  "360-"  then  it  is 
a  nra-native  type.  The  accompanying  GFD  explicitly  lists  the 
GFA  s  of  the  file.  The  LFA's  are  unknown  and  irrelevant  in  this 

case. 


*  If  the  GET  does  begin  with  the  characters  "360- "  then  it  is  a 
native  GFD  and  the  accoiq>anying  GFD  can  be  ignored;  the  ^A's 
LFA's,  and  default  PSA's  for  that  GET  are  taken  from  the  local 
table. 

The  contents  of  the  GFD  are  covered  in  a  later  section  entitled 
NSV  FILE  ATTRIBUTES. 
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2.1.3.  PROCEDURE  CALLS  SUPPORTED 


2. 1.3.1.  TRANSPORT 

The  Transport  procedure  copies  a  local  or  remote  file  into  a  local 
disk  data  set,  converting  the  data  to  specified  target  attributes. 
In  the  NSW  context,  the  Transport  procedure  should  be  used  only 
with  source  and  target  files  outside  the  NSW  fllespace;  however, 
FP/360  can  make  no  check  on  this. 

The  form  of  the  Transport  procedure  call  is: 


FP-TRANS  (input  PCD, 

input  PASSWORD, 
input  GFT, 
input  GFD, 

output  PCD, 
output  PASSWORD, 
output  GFT, 
output  GFD) 

->  0 


This  call  creates  s  local  copy  of  a  local  or  remote  file,  using  a 
name  determined  from  the  DIRECTORY  and  NAME  fields  of  "output 
PCD".  Since  the  actual  name  used  is  not  returned  to  the  caller, 
"output  PCD"  should  Include  a  fully  specified  name.  If  this  name 
is  a  duplicate,  FP/360  will  delete  the  old  copy. 

If  "input  PCD"  specifies  a  remote  host.  Transport  will  issue  a 
SendMe  call  to  the  FP  on  that  host  to  retrieve  the  file. 

The  operation  may  fail  if  it  is  not  possible  to  translate  from  the 
attributes  implied  by  "input  GFT"  and  "input  GFD"  to  those  of 
"output  GFT". 

Transport  returns  no  reply  except  the  usual  completion  mode  (REPLY 
vs.  ERROR). 

Version  2  restriction:  the  target  file,  and  the  source  file  if 
local,  must  be  in  the  NSW  directory  group. 
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IMPORT 

The  Import  procedure  makes  an  exact  copy  of  a  local  or  remote  file 
Into  a  local  disk  data  set  in  the  NSW  filespace  directory.  No 
data  type  conversion  is  performed;  the  output  file  is  assumed  to 
have  the  same  6FT  (and  GFD)  as  the  input  file.  The  form  of  the 
Import  procedure  call  is: 

FP-IMP  (input  PCT, 

input  Password 
input  GFT, 
input  GFD, 

output  file  identifier, 
delete  switch) 

->  (output  PCD) 

If  ** input  PCD”  specifies  a  remote  host.  Import  will  issue  a  SendMe 
call  to  the  FP  on  that  host  to  retrieve  the  file.  The  output  will 
be  encoded  in  IL  if  the  input  is  a  local  file  in  IL  or  if  it  is 
received  from  a  remote  host  in  IL  (Note:  It  is  presently  planned 
to  use  IL  for  cross -network  transfer  of  all  files,  even  within  the 
360/370  family). 

If  the  copy  is  completed  successfully,  FP/360  returns  an  "output 
PCD”  which  describes  the  new  data  set.  In  particular.  Import 
takes  the  DIRECTORY  from,  and  generates  a  random  NAME  from,  the 
NSW-fllespace  default  fields  of  the  initialization  parameters. 

The  "output  file  identifier”  is  always  ignored. 

The  Boolean  parameter  "delete  switch”,  if  true,  specifies  that  the 
input  file  is  to  be  deleted  after  a  successful  copy.  This  option 
may  be  set  only  for  a  local  input  file,  in  which  case  FP/360  will 
attempt  to  iagilement  the  procedure  as  a  data  set  rename.  No  data 
iDovement  will  occur,  and  "output  PCD"  will  be  a  copy  of  "input 
PCD”  with  new  values  for  the  directory  and  name. 
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2. 1.3.3.  EXPORT 

The  Export  procedure,  like  Transport,  makes  a  local  copy  of  a 
local  or  resKite  file,  with  data  t3^e  conversion.  However,  the 
Export  procedure  has  three  additional  options,  discussed  ^low. 

FP'EXP  (LIST  (iiq>ut  PCD  candidates), 
input  6FT, 
input  GFD, 

output  PCD  skeleton, 
output  PASSWORD, 

LIST  (output  6FT  candidates), 
write  secondary  output  switch, 
output  FII£  IDENTIFIER) 

->  (output  PCD, 

secondary  output  PCD, 
output  GFT) 

The  "output  PCD  skeleton"  will  usually  contain  a  non-null 
DIRECTORY.  The  NAME  field  may  contain  either  a  fully  specified 
name  or  wild  characters  to  be  replaced  in  such  a  way  as  to  create 
a  unique  name.  If  a  fully  specified  name  matches  an  existing  data 
set,  then  FP/360  will  delete  the  existing  copy.  If  no  NAME  is 
specified,  the  NAME  default  for  non-NSW  filespace  will  be  used. 
Similarly,  if  OISECTORY  is  not  specified,  a  default  non-NSW 
directory  will  be  taken  from  the  initialization  parameters. 

The  three  additional  options  of  Export  are: 

1)  Export  chooses  the  input  file  from  "input  PCD  candidates". 
It  will  order  this  list  of  input  candidates  by  estimated 
ease  of  copy,  using  this  simple  preference  definition: 

1)  a  local  data  set  not  encoded  in  IL. 

2)  a  local  data  set  encoded  in  IL. 

3)  a  remote  data  set  encoded  in  IL. 

4)  a  resmte  data  set  not  encoded  in  IL. 

Having  fonoed  this  sorted  list  of  input  PCD's,  FP/360  loops 
down  the  list  and  attempts  to  copy  each  in  turn,  until 
either:  1)  a  successful  copy  is  produced;  2)  the  list  is 

exhausted;  or  3)  the  number  of  attempts  exceeds  a  limiting 
value  acquired  as  an  FP/360  initialization  parameter. 
Setting  that  parameter  to  1  effectively  disables  retry. 

2)  From  "output  GFT  candidates".  Export  must  choose  a  sixigle 
GFT  for  its  prloiary  output. 
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*  If  the  list  of  output  6FT  candidates  is  empty,  then  the 
input  6FT  will  be  used. 

*  If  the  input  GFT  appears  in  the  list  of  output  GFT 
candidates,  it  will  alwajrs  be  selected. 

*  Otherwise,  the  list  of  candidates  is  sorted  into  order  of 
Increasing  cost  of  conversion,  while  preserving  the 
original  order  in  cases  of  equal  cost  (the  list  was 
originally  ordered  by  the  caller's  preference).  The 
algorithm  for  this  sort  is  described  in  the  section 
entitled  "CONVERSIONS  IN  FP/360".  The  first  GFT  on  the 
sorted  list  is  selected. 

*  It  is  possible  that  none  of  the  conversions  from  the  input 
GFT  to  any  of  the  output  GFT's  are  possible.  In  this 
case,  the  entire  Export  operation  is  failed. 

3)  Export  can  create  a  secondary  output  file  in  the  sasM  format 
and  with  the  same  type  as  the  input. 

If  "write  secondary  output  switch"  is  true,  FP/360  is 
requested  to  create  a  secondary  copy.  How,ever,  Export  has 
the  privilege  of  refusing  to  do  so  if  the  copy  would  be 
redundant,  due  to  the  existence  of  a  local  data  set  among 
the  input  PCD  candidates.  Refusal  is  indicated  by  returning 
a  null  "secondary  output  PCD"  to  the  Works  Manager. 

Otherwise,  Export  will  create  a  data  set  containing  the 
records  exactly  as  they  are  received  from  the  donor  file 
package.  The  name  for  the  secondary  output  data  set  is 
always  generated  by  FP/360  using  the  sasM  mechanism 
described  earlier  for  naming  the  result  of  the  Import 
procedure,  but  using  the  NSW  fllespace  defaults  in  the 
initialization  parameters. 

Version  2  restriction:  the  entire  Export  procedure  will  fail  if 
any  unrecoverable  error  occurs,  even  one  not  preventing  producing 
the  primary  output  data  set. 


Supporting  the  IBM  File  System  in  NSW 
November  20,  1980  *■-  Part  II:  FF/360 

PAGE  12 


SENDME 

The  SendMe  procedure  copies  a  file  from  a  local  disk  data  set  to  a 
remote  FP  through  a  binary  direct  connection.  The  data  will  be  be 
encoded  into  NSW  IntersMdiate  Language  (IL),  and  all  local 
file-type  dependencies  will  be  stripped  from  it.  However,  no  data 
type  conversion  is  performed  —  the  output  6FT  is  identical  to  the 
input  6FT. 

The  form  of  the  SendMe  procedure  call  is: 

FP-SENDME  (input  PCD, 

input  PASSWORD, 
input  6FT, 
input  6FD, 

receiver  host  nuiril>er, 
maxianim  b3rte  size, 
maximum  block  size, 
family  argument) 

->  (connection  identifier, 
actual  byte  size, 
actual  block  size, 
file  size, 
family  reply) 

The  ** input  GFD"  is  actually  redundant.  Either  the  data  to  be 
transmitted  is  of  a  native  type,  in  which  case  its  attributes  are 
known,  or  it  is  in  IL,  in  which  case  no  attributed  will  need  to  be 
known  to  transmit  it.  So  this  datum  is  effectively  Ignored. 

The  actual  block  size  will  be  the  mlniaum  of:  1)  the  requested 

maximum  block  size;  and  2)  a  limiting  value  acquired  as  an  FP/360 
initialisation  parameter.  At  present,  transmission  block  sizes 
are  established  by  Gentlemen's  agreement,  and  will  not  vary. 
Therefore,  if  the  input  is  IL-encoded,  and  if  one  of  its 
pre-formatted  IL  transmission  blocks  exceeds  this  block  size,  the 
procedure  will  be  aborted. 

The  "file  size"  result  will  be  the  bit  size  of  the  actual  disk 
allocation  on  the  local  disk,  adjusted,  if  the  data  set  is  not 
already  in  IL,  by  its  LFD's  "compression  factor"  attribute. 

Version  2  restrictions: 

*  The  receiver  host  number  is  already  known,  so  the  corresponding 
parameter  is  ignored. 
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"CoanectlMi  identifier”  is  always  1. 

”Actual  byte  size”  is  always  8. 

Non-IL  transmission  is  not  supported:  therefore,  "family 

argument”  is  ignored,  and  "family  reply”  will  always  be  EMPTY. 

SendMe  cannot  generate  alatsm.  Any  terminal  error  condition 
will  be  signalled  by  closing  the  direct  connection  without 
sending  the  end-of-transmission  indicators. 
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2. 1.3.5.  DELETE 

The  Delete  procedure  call  is  the  only  "collective"  operation 
implemented  in  FP/360.  The  form  of  the  Delete  procedure  call  is: 

FP'DEL  (LIST  (local  pcd)) 

->  (LIST  (error  descriptor)) 

where  the  argusMnts  are  physical  copy  descriptors  defining  the 
data  sets  to  be  deleted,  and  the  result- list  is  either  empty  or  a 
list  of  corresponding  error  descriptors.  The  possible  results 

are: 

*  If  all  specified  deletions  are  successful,  the  entire 

transaction  completes  in  REPLY  mode  (reference  3) ,  and  the 
result- list  is  replaced  by  a  LIST  of  count  0. 

*  If  there  is  an  error  that  relates  to  the  procedure  call  as  a 
whole,  the  transaction  completes  in  ERROR  mode  (reference  3)  and 
the  result-list  is  a  LIST  of  count  0. 

*  Otherwise  -•  if  there  is  one  or  more  errors  relating  to  the 

deletion  of  specific  data  sets  in  the  argument  list  --  then  the 
entire  transaction  completes  in  ERROR  mode  (reference  3),  with 
the  main  NIP  error  descriptor  specifying  "partial  results 
returned".  In  addition,  the  result-list  contains  a  result 
descriptor  for  each  specific  PCD.  Each  of  these  descriptors  is 
either:  a  null  list,  if  the  deletion  was  successful,  or  a  list 

of  the  form 

LIST  (errorclasa,  ermumber,  errorstring) 

Notice  that  errors  associated  with  a  single  PCD  have  no  effect 
on  the  processing  of  other  PCD's. 

Version  2  restriction:  The  Checkpointer  is  now  sending  the  Delete 
call  using  another  syntax  —  the  single  PCD  is  not  enclosed  in  a 
list.  For  now,  that  form  is  the  one  recognized  by  FP/360. 
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ANALYZE 

The  Analyze  procedure  is  currently  incompletely  defined. 
Therefore,  in  FP/360,  Analyze  is  a  no-operation  corresponding  to 
the  form: 
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NSW  FILE  ATTRIBUTES 

An  NSV  file  is  really  an  abstraction,  standing  for  a  collection  of 
equivalent  physical  copies.  The  location  of  each  physical  copy  is 
defined  by  an  NSW  data  structure  called  a  Physical  Copy  Descriptor, 
or  PCD.  All  physical  copies  of  the  same  NSW  file  share  the  same 
Global  File  Attributes,  or  GFA's. 

The  GFA's  of  an  NSW  file,  and  thus  of  the  data  in  a  local  copy,  are 
passed  to  an  FP  in  the  form  of  a  character  string  called  a  "Global 
File  Type",  or  GFT.  This  string  consists  of  a  prefix  part  which  is 
the  NSW  "host  family  name"  ("360"  for  the  family  to  which  FP/360  is 
native),  followed  by  a  hyphen,  followed  by  a  suffix  part  chosen  to 
be  unique  and  mnemonic  within  the  "family".  Such  a  name  represents 
very  nearly  the  complete  set  of  data  attributes  that  a  particular  FP 
must  know  about  the  local  copy. 

In  FP/360,  attributes  are  structured  into  three  discrete  levels; 
however,  it  should  be  recognized  that  the  assignment  of  attributes 
to  <»e  level  or  the  other  is  more  an  engineering  (if  not  political) 
decision  than  a  theoretical  consequence.  As  a  result  of  future 
experience  with  the  NSW,  additional  attributes  may  be  added  to  the 
global  set,  the  driving  force  being  tool  installers  and  users  who 
want  data  type  mismatches  to  be  handled  automatically  by  the  NSW 
mechanism. 

*  Global  File  Attributes 

Global  File  Attributes  (GFA's)  are  basic  ones  that  apply  to  the 
data  within  a  file,  whether  it  is  represented  in  IL  or  not.  These 
most  be  the  same  for  all  copies  of  that  file.  They  are  uniformly 
defined  across  all  NSW  host  families.  The  character/binary 
distinction  is  a  good  example. 

While  these  attributes  are  strictly  implied  by  the  GFT,  their 
derivation  is  always  perfonoed  by  the  Works  Manager,  in  order  that 
FP/360  need  not  be  aware  of  the  meanings  of  GFT's  not  native  to 
the  360  family.  These  derived  attributes  are  packaged  into  the 
Global  File  Descriptor,  or  GFD.  A  GFD  is  always  shipped  along 
with  a  GFT  when  the  Works  Manager  sends  the  GFT  to  FP/360,  with 
one  exception:  the  output  file  type  of  the  Export  procedure  is 
represented  only  by  a  GFT  because  that  GFT  is  guaranteed  to  be 
native  to  the  360  family.  FP/360  keeps  a  table  of  the  attributes 
of  all  native  types,  and  this  table  includes  the  information  in 
the  corresponding  ^D's. 


*  Local  File  Attributes 
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Local  File  Attributes  (LFA's)  describe  the  way  that  data  of  a 
given  type  is  represented  in  non-IL  ("clear  text")  form  within  the 
360  family.  The  coluomar  position  of  a  key  field  is  a  good 
example.  These  attributes  are  derived  from  the  GFT  for  any  native 
t3npe  by  FP/360.  The  LFA's  provide  the  Instructions  needed  by 
FP/360  to  translate  data  between  IL  string  encodement  and  the 
clear  text  encodement  implied  by  the  GFT. 

*  Physical  Structure  Attributes 

Physical  structure  Attributes  (PSA's)  describe  the  specific 
mapping  of  a  data  set  on  disk.  On  an  IBM  360,  the  DCB  parameters 
are  a  good  example. 

PSA's  are  handled  differently  depending  on  whether  FP/360  is 
assigning  them  to  a  newly  created  data  set  or  determining  those 
already  assigned  to  an  existing  data  set.  In  the  former  case, 
default  values  can  be  derived  from  the  GFT  and  embellished  by 
anything  known  about  the  quantity  of  data  the  file  is  expected  to 
contain.  In  the  latter  case,  most  PSA's  are  stored  by  the  TBH 
operating  system  as  part  of  the  data  set  label,  and  are  available 
to  FP/360  on  request. 

NSW  provides  that  PSA's  that  are  not  automatically  available  will 
be  kept  by  the  Works  Manager  in  a  PCD  field  named  PHYS.  The  PCD 
is  always  available  whenever  FP/360  accesses  an  existing  file,  so 
the  PHYS  field  information  is  always  available  when  it  is  needed. 
However,  since  the  PSA's  used  by  FP/360  are  kept  by  the  local 
operating  system,  FP/360  currently  has  no  need  for  the  PHYS  field. 

One  special  case  should  be  noted.  For  each  physical  copy,  an  FP 
will  need  to  know  whether  it  is  physically  encoded  in  IL.  Since 
this  attribute  is  not  kept  by  any  existing  host  system,  and  since 
it  is  meaningful  across  all  NSW  host  families,  it  is  kept  in  a 
special  field  of  the  PCD  named  ILFLAG. 
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2. 1.4.1.  GWBAL  FILE  ATTRIBUTES 

As  noted  earlier,  FP/360  may  obtain  the  GFA's  from  the  6FD  (for  a 
non-native  type)  or  from  its  own  local  table  (for  a  native  type). 
In  either  case,  FP/360  interprets  the  GFA's  in  the  following 
manner: 

2. 1.4. 1.1.  CLASS 

This  field  determines  whether  the  data  consists  of  characters  or 
binary  bytes,  with  the  following  consequences. 

*  Character-class  data  represents  an  array  of  ASCII  graphics  of 
dimensionality  between  1  and  4  (see  the  dicussion  of 
dimensionality  below).  A  full  cooiplement  of  format  effectors 
is  defined  for  use  in  positioning  graphics  within  the  array. 
Unspecified  array  positions  are  assumed  to  contain  the  fill 
character  "blank",  which  is  also  used  for  optimal  coaq>ression 
in  IL. 

Data  with  dimensionality  of  2  or  higher  is  organized  into 
"records",  with  which  there  may  be  associated  character-string 
"keys".  A  cncamon  use  of  these  keys  is  to  repord  the  "sequence 
nui^rs"  associated  with  text  lines  by  some  text  editors, 
ea^>ilers,  etc. 

*  Binary-class  data  is  of  dimensionality  1  or  2,  representing 
either  a  single  byte  string  or  a  sequence  of  (short)  b3rte 
strings  called  "records”,  respectively.  There  are  no  format 
effectors  other  than  the  record  separators .  In 
two-dimens icmal  data,  a  record  may  be  associated  with  a 
character-string  key  as  well  as  the  binary  text. 

For  binary-class  data,  the  "fill"  character  used  for  IL 
compressimi  is  a  byte  of  binary  zeros. 

2. 1.4. 1.2.  EXT  DEFINITIONS 

When  keys  are  associated  with  data  records  of  the  file,  the  keys 
are  alw^T*  character  strings.  The  GFA's  for  keys  are  a  Boolean 
"keys  present”  Indicator  and  an  integer  "key  length"  field. 

2. 1.4. 1.3.  VARIABLE  FORMAT  EFFECTORS 

Format  effectors  can  be  classified  as  regular  and  irregular, 
with  the  regular  ones  further  classified  as  horizontal  or 
vertical,  as  interval  or  absolute,  as  positive  or  negative,  and 
as  fixed  or  variable  (see  figure  1).  The  fixed  format  effectors 
are  interpreted  the  same  for  all  files  and  by  all  FP 
laplamentstlons  (by  system-wide  convention.  Carriage  Return  and 
Backspace  are  always  considered  to  be  non-destructive) .  The 
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variable  format  effectors  are  defined  in  the  GFD  under  the  name 
TAB -DESCRIPTOR  and  can  thus  be  interpreted  the  same,  for  a  given 
file  type,  by  all  FP  implementations. 

FP/360  will  be  able  to  support  expansion  of  all  defined  format 
effectors  received  from  remote  FP's.  However,  when  encoding 
files  of  native  global  types,  FP/360  will  generate  only  regular 
positive  fixed  forms  and  the  irregular  "SKIP(O)"  form,  i.e., 
only  IL  types. 
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Figure  1:  Classification  of  Format  Effectors 


REGUUR  HORIZONTAL  TYPES: 

Interval  positive  (<1>0) —  (Variable):  HT  as  Interval 


Interval  negative  (d>0) — 


(Fixed) :  Destructive  BS 

(not  in  ASCII) 


Absolute  positive  (d>l)--  (Variable):  HT  as  stop  list 


Absolute  negative  (d>l) — 


(Fixed) :  Destructive  CR 

(not  in  ASCII) 


REGULAR  VERTICAL  TYPES: 


Interval  positive  (d>l)’*- 


(Variable):  LF,  VT  as  interval,  or 
(Fixed):  IL  "skip  n"  (n>0) 

record  control. 


Interval  negative  (d>l)  — 


Absolute  positive  (d>2)‘''* 


(fixed) :  Inverted  linefeed 

(not  in  ASCII) 

(Variable):  FF,  VT  as  stop  list,  or 
(Fixed):  IL  NewPage 


Absolute  negative  (d>2)'**’  (none  defined) 


IRREGULAR  TYPES: 


(d>3)-*  Non'destructive  backspace 
(d>3)->  Non'destructive  carriage  return 
(d>3)--  IL  "skip  O"  record  control 
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2. 1.4. 1.4.  DIMENSIONALITY 

FP/360  copies  a  file  in  the  form  of  a  one-dimensional  stream  of 
characters  or  binary  bytes.  However,  this  stream  is  understood 
to  represent  an  array  of  more  complex  structure,  with  up  to  four 
meaningful  dimensions.  The  logical  equivalence  of  physical 
copies  of  the  same  NSW  file  is  properly  stated  in  terms  of 
equivalence  of  the  multidimensional  array  rather  than  that  of 
the  stream  used  for  transmission.  Thus  FP/360  must  concern 
itself  with  preserving  the  integrity  of  that  array.  In 
particular,  FP/360  Interprets  the  dimensionality  in  the 
following  manner: 

2. 1.4. 1.4.1.  DIMENSIONALITY  s  1 

One -dimensional  data  consists  of  a  stream  of  bytes  (or 
characters)  that  are  not  logically  grouped  into  lines  or 
records.  The  single  dimension  corresponds  to  file  size,  and 
is  effectively  unbounded. 

(  BYTE  [  c  ] ,  cs  1  to  file^size  } 

For  character-class  files,  regular  horizontal  format  effectors 
(see  Figure  1)  axe  possible,  but  no  other  format  effectors 
would  be  meaningful.  The  data  may  be  broken  arbitrarily  into 
record-like  strings  for  convenience  in  handling,  but  it  is 
understood  that  these  strings  are  not  logical  records. 

IL  "record  control"  fields  have  no  meaning;  FP/360  will  ignore 
them  when  receiving  and  will  generate  "SKIP(O)"  when 
transmitting. 

Logical  equivalence  of  one-dimensional  file  copies  is  defined 
to  be  equivalence  of  the  byte  or  character  streams  represented 
by  the  encodement  (i.e.,  after  IL  expansion),  regardless  of 
the  class  of  the  data. 


A  one-dimensional  file  cannot  have  keys. 

2. 1.4. 1.4.2.  DIMENSIONALITY  -  2 

TVo-dimenslonal  data  consists  of  a  stream  of  bytes  (or 
characters)  divided  into  records  or  lines.  Keys  are 

permitted,  and  if  they  appear  there  is  a  key  included  with 
each  record.  The  first  dimension  is  bounded  by  the  "Record 
Length  Range"  datum  of  the  UD,  but  the  second  corresponds  to 
file  size,  and  is  effectively  unbounded. 
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2. 1.4. 1.4.3. 


2. 1.4. 1.4.4. 


(  KEY  [  k,  r  ],  BYTE  (  c,  r  ], 


for:  c«  1  to  max-record'text- length, 

1  to  key-width, 

r«  1  to  record-count,  ) 


For  character-class  files,  it  is  possible  to  define  any  kind 
of  regular  horizontal  format  effectors  and  regular  vertical 
interval  format  effectors,  but  no  other  kind  are  meaningful. 


Equivalence  of  two-dimensional  file  copies  is  defined  to  be 
equivalence  of  the  two  right-ragged  arrays  represented  by  the 
data  encodement  (i.e.,  after  IL  expansion),  and  when 
appropriate,  of  corresponding  keys.  The  right  edges  are 
defined  to  include  trailing  "fill  characters"  as  a  part  of  the 
data. 


DIMENSIONALITY  «  3 


Three-dimensional  data  consists  of  a  stream  of  characters, 
grouped  into  lines,  which  are  then  grouped  into  pages.  Keys 
are  legal,  but  will  probably  be  rare.  The  first  dimension  is 
bounded  by  the  "Record  Length  Range"  datum  o.f  the  LFD,  and  the 
second  by  the  "page  depth"  datum,  but  the  third  corresponds  to 
file  size,  and  is  effectively  unbounded. 


{  KEY  I  k,  r,  p  1.  BYTE  I  c,  r,  p  1, 


c«  1  to  max-record-text-length, 
k*  1  to  key-width, 
r*  1  to  page-depth, 
p«  1  to  page-count  } 


Only  character-class  data  can  be  three-dimensional,  and  it  is 
meaningful  to  define  all  regular  format  effectors. 


Equivalence  of  three-dimensional  file  copies  is  defined  to  be 
graphical  equivalence  of  the  two  arra3rs  represented  by  the 
data  encodement  (i.e.,  after  IL  expansion),  and  when 
appropriate,  of  corresponding  keys.  The  ri^t  edges  are 
ragged  in  all  dimensions,  and  are  defined  to  exclude  trailing 
"fill  characters"  from  significance  as  data. 


DIMENSIONALITY  >  4 


Four -dimensional  data  consists  of  a  stream  of  characters, 
grouped  into  records,  which  are  then  grouped  into  lines,  which 
SfZ  then  be  grouped  into  pages.  Keys  are  legal,  but  will 
probably  be  rare.  The  first  dimension  is  bounded  by  the 
''Record  Length  Range"  datum  of  the  LFD,  and  the  second 
corresponds  to  overprinting  and  is  unbounded.  The  third 
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dimension  is  bounded  by  "page  depth",  while  the  fourth 
corresponds  to  file  size  and  is  also  unbounded. 


{  KEY  (  k,  i,  1,  p  1.  BYTE  t  c,  r.  1,  p  ], 

for:  c*  1  to  max-record-text- length, 

k»  1  to  key-width, 
r^  1  to  max-overprint-depth. 

Is  1  to  page -depth, 

ps  1  to  page-count  } 

Only  text-class  data  can  be  four -dimensional,  and  it  is 

meaningful  to  define  all  regular  and  Irregular  format 
effectors . 

Equivalence  of  four-dimensional  file  copies  is  defined  to  be 
graphical  equivalence  of  the  two  arrays  represented  by  the 
data  encodement  (l.e.,  after  IL  expansion),  and  when 

appropriate,  of  corresponding  keys.  The  ri^t  edges  are 
ragged  in  all  dimensions,  and  are  defined  to  exclude  trailing 
"fill  characters"  from  significance  as  data. 


'i* 


2. 1.4. 1.5.  BYTESIZE 


A  file  may  consist  of  bytes  of  a  width  in  the  range  8  -  255 
bits;  however,  FP/360  will  refuse  to  process  files  with  a 
bytes Ize  other  than  8. 
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2. 1.4.2. 


2. 1.4.2. 


2. 1.4.2. 


2. 1.4.2. 


2. 1.4.2. 


2. 1.4. 2. 


2. 1.4.2. 


2. 1.4.2. 


LOCAL  FILE  ATIItlBUTES 

FP/360  gets  its  LFA's  from  a  Local  File  Descriptor  (LFD)  which  is 
stored  locally  and  retrieved  via  the  GFT.  The  fields  of  this 
descriptor  are  listed  below. 

It  is  important  to  understand  that  values  for  certain  LFA's  are 
often  required  by  FP/360  even  when  thay  do  not  appear  to  have 
meaning  for  the  particular  data  type.  This  is  because  they  may  be 
needed  to  perform  a  type  conversion  into  that  type  from  a 
non-native  type  about  which  nothing  is  known.  For  example,  a 
"page  depth"  datum  is  tabulated  for  a  two-dimensional  data  type  if 
conversion  of  non-native  three-dimensional  data  into  that  type 
could  occur,  even  though  page  depth  has  no  meaning  for  an  existing 
two-dimensional  file. 

In  the  following,  some  variables  have  as  a  value  an  indicator  that 
user  permission  is  to  be  obtained  via  the  NSW  HELP  mechanism.  In 
Version  2,  that  mechanism  is  not  available  to  FP/360,  so  these 
permissions  are  assumed  to  be  granted. 

Certain  of  the  LFA's  are  now  required  by  NSW  convention  to  be  set 
in  certain  ways.  For  instance,  it  has  now  been  decided  that 
trailing  fill  characters  are  always  significant  in  one-  or 
two-dimensional  data. 

Dimensionality  preference  —  this  datum  defines  a  preference 
ordering  of  the  four  dimensionalities  for  situations  where 
dimensional  conversion  sMy  be  required.  For  each,  a  flag 
Indicates  whether  conversion  from  that  dimension  is  permitted, 
forbidden,  or  permitted  only  with  explicit  user  permission. 

Min  Record  Length,  Max  Record  Length  —  These  two  fields  give 
the  miniaium  and  maximum  number  of  bytes  of  text  (exclusive  of 
keys)  that  a  record  of  this  type  can  contain. 

Short  record  handling  —  pad,  signal  error,  or  ask  user. 

Long  record  handling  --  truncate,  fold  (make  two  records),  ask 
user,  or  signal  error. 

Record  fold  margin  —  what  column  continuations  begin  in. 

Page  depth  --  the  number  of  lines  (not  records)  to  a  printer 
page. 

Short  page  handling  --  pad,  leave  as-is,  or  ask  user. 
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2. 1.4. 2. 8. 


2. 1.4. 2. 9. 


Long  page  handling  truncate,  fold  (make  two  pages),  leave 
as-is,  or  ask  user. 

Key  position  1-origin  index  of  the  text-field  byte  before 
which  the  key  is  to  appear. 


10. 


How  to  generate  missing  keys  —  don't  (signal  error),  count 
records,  blank  fill,  delete  field,  or  ask  user. 


2. 1.4.2 

2.1.4.2.11.  Option  switches: 


Force  upper  case 
Suppress  code  translation 
Suppress  IL  expansion 
Input -only  type 

Trailing  fill  characters  are  significant 

2.1.4.2.12.  Format  effector  handling  switches: 

Horizontal  tab  handling: 

Leave  as  tab  code. 

Expand  by  input  GID,  or 
Expand  by  output  GFD. 

Vertical  format  effector  handling  (For  each  of  VT,  LF,  and 
FF): 

Leave  as  EBCDIC  code, 

Expand  by  input  GFD,  or 
Expand  by  output  GFD. 

Backspace  handling: 

Leave  as  backspace  code. 

Expand  destructively,  or 
Expand  non-destructively. 

Carriage  return  handling: 

Leave  as  carriage  return  code. 

Expand  destructively,  or 
Expand  non-destructively. 

2.1.4.2.13.  Compression  factor  --  typical  IL  bytes/"clear  text"  bytes. 
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2. 1.4.3.  PHYSICAL  STORAGE  ATTRIBUTES 

FP/360  gets  its  PSA's  for  sn  existing  dsts  set  from  the  dsts  set 
Isbel.  When  cresting  s  aeir  dsts  set,  recommended  PSA's  sre 
tsbulsted  in  s  descriptor  (the  PSD)  which  csn  be  retrieved  vis  the 
GFT.  Its  fields  sre: 

*  DSORG  the  dsts  set  orgsnizstion. 

FP/360  will  support  only  Physicsl  Sequentisl  (DSORG^PS)  in 
Version  2. 

'*  RECFH  —  the  record  formst. 

In  Version  2,  FP/360  will  support: 

F  [B[S]][A]  (fixed-length  records) 

V  [B] [S] [a]  (vsrisble- length  records) 

U  [A]  (undefined- length  records) 

*  OPTCD  —  dsts  msnsgment  option  codes. 

FP/360  will  not  support  sny  of  these  in  Version  2. 

*  LRECL  —  logicsl  record  length. 

*  BLXSIZE  --  physicsl  block  size. 

TWo  vslues  sre  tsbulsted.  FP/360  msy  choose  s  vslue  within  thst 
rsnge  which  is  compstible  with  RECFH  end  LRECL,  snd  which 
optimizes  utilizstion  of  the  selected  physicsl  device.  If  the 
two  vslues  sre  the  ssme,  then  no  vsristion  in  block  size  is 
si lowed. 

*  KETI£N  --  length  of  rsndom-sccess  retrievsl  key. 

*  RKP  —  offset  of  rsndom-sccess  retrievsl  key. 

Version  2  does  not  support  rsndom  sccess  to  dsts  sets,  so 
non-zero  vslues  of  KEYI£N  snd  RKP  will  not  occur. 

*  SPACE  --  recommended  sllocstion  if  no  size  dsts  is  svsllsble. 

There  sre  three  fields  —  PRIMARY,  SECONDARY,  snd  DIRECTORY. 
The  first  snd  second  fields  sre  initsl  snd  subsequent  sllocstion 
qusntitles  in  selected-blocksize  units.  The  third  field  is 
relevsnt  to  psrtitioned  dsts  set  orgsnizstion,  snd  so  is  not 
currently  supported.  It  will  slwsys  be  zero. 
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Hia*PING  FILES  ON  A  360 

Under  FP/360,  a  file  encoded  in  IL  is  recorded  on  disk  according  to 
these  conventions: 

1)  The  data  set  organization  is  Physical  Sequential  (DSORG^PS). 

2)  The  record  format  is  Variable  Blocked  (RECFM^VB)  or  Variable 
Blocked  Spanned  (RECFM^VBS),  depending  on  the  values  selected 
for  LRECL  and  BLKSIZE. 

3)  Each  logical  record  is  one  IL  transmission  block.  The  maximum 
logical  record  length  (LRECL)  is  four  greater  than  the 
corresponding  SendHe  procedure  transmission  block  size,  since 
disk  records  have  count  and  control  fields  four  bytes  long, 
and  the  transmission  block  size  does  not  include  even  the 
2-byte  IL  count  fields. 

4)  The  data  set  maximum  block  size  (BLKSIZE)  is  independent  of 
the  data.  It  is  selected  by  FP/360  by  choosing  a 
device -optimizing  value  between  two  limits  provided  it  as 
initialization  parameters. 

5)  The  data  in  the  data  set  can  be  considered  free  of  any  LFA's, 
whether  or  not  its  GFT  is  360-native. 
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2.1.6.  CONVERSIONS  IN  FP/360 

A  Transport  or  Export  operation  may  create  a  new  file  with  a 
different  GFT  than  the  input  file;  the  change  of  the  file  contents 
as  a  result  is  called  "conversion"  of  the  file.  Notice  that  such 
type  conversion  may  take  place  only  when  the  target  file  is  outside 
NSW  file  space 

*the  original  GFT  is  always  preserved  within  NSW  file 

space. 

2. 1.6.1.  TRANSUTABILIT7 

The  translatabllity  of  a  file  is  a  function  of  its  existing  GFT 
and  the  desired  new  GFT,  or,  more  precisely,  of  an  input  GFD  and 
an  output  GFT,  GFD,  and  LFD.  A  legal  translation  will  have  all 
the  following  properties,  and  need  have  none  other: 

1)  The  output  GFT  is  native  to  the  360  family. 

2)  The  input  and  output  data  classes  (binary  vs.  character)  are 

the  same. 

3)  The  input  dimensionality  is  one  that  is  permitted  by  the 
output  LFD. 

4)  Either  the  input  has  keys,  or  the  output  does  not  have  keys, 
or  the  output's  "how  to  generate  missing  keys"  datum  doesn't 
contain  the  value  "don't". 

5)  The  Bytesixe  fields  match. 

For  purposes  of  selecting  the  primary  output  GFT  which  is  "best", 
FP/360  defines  a  "dimensionality  preference"  table  in  the  GFD  for 
each  output  type.  The  table  contains  four  entries,  one  for  each 
of  the  possible  input  dimensionalities.  An  entry  actually 
consists  of  two  parts:  a  three-state  translatabllity  flag  with 
values : 

*  "permitted" 

*  "permitted  with  user  permission" 

"not  permitted" 

and  a  preference -rank  number  (ignored  for  "not  permitted" 
entries).  Version  2  of  FP/360  will  not  support  asking  users  for 
permission,  so  those  in  the  second  category  are  treated  as 
"permitted",  but  with  lower  preference  than  those  in  the  first 
category.  Version  2  will  therefore  select  the  target  GFT  with 
"permitted"  dimensionality  and  the  highest  rank  number,  or  if  none 
are  "permitted",  the  one  "permitted  with  user  permission"  and 
highest  rank  number. 
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2. 1.6.2.  DIMENSIONAL  CONVERSION 

When  a  file  is  entered  into  NSW  file  space,  its  GFT  and  therefore 
its  dimensionality  attribute  must  be  declared.  This  attribute 
specifies  the  maximum  dimensionality  that  the  file  might  have,  and 
that  the  eventual  user  of  the  file  must  be  prepared  to  handle; 
however,  the  actual  file  contents  might  in  fact  be  of  lower 
diaransionality.  If  a  host  "lies”  and  declares  all  its  files  to  be 
of  dimensionality  4,  many  tools  may  refuse  to  process  these  files 
as  input.  However,  there  may  be  no  harm  in  a  paper-tape  host 
declturing  every  file  to  have  dimensionality  3. 

Any  data  of  dimensionality  "n”  is  also  legal  data  of 
dimensionality  "n*fl”,  where  the  bound  of  the  new  dimension  is  one. 
However,  the  converse  is  not  true.  In  particular,  when  FP/360  is 
instructed  to  reduce  the  dimensionality  of  a  4-dimensional  file, 
it  must  make  potentially  destructive  changes.  By  external 
conventions,  all  native  types  permit  conversion  out  of  any  higher 
dimensionality  only  with  explicit  user  permission;  however,  if 
there  is  no  user  to  ask,  the  conversion  is  permitted. 

In  general,  a  conversion  which  lowers  the  dimensionality  by  n  can 
be  defined  in  terms  of  a  series  of  n  conversions,  each  lowering 
the  dimension  by  1.  In  all  cases  the  surfaces  of  the  unwanted 
dimension  collapse  into  a  plane,  somewhat  as  does  a  closing 
Venetian  blind.  This  has  the  correct  default  property:  if  the 
data  is  in  fact  of  the  lower  dimensionality  already,  it  will  be 
unchanged  by  the  transformation. 

2. 1.6.2. 1.  CONVERTING  4  TO  3 

This  is  an  information-destroying  conversion.  Each  page 
consists  of  a  primary  page  surface  and  an  unbounded  number  of 
overprint  page  surfaces.  Cross  sections  of  these  surfaces  are 
lines.  Tlie  intersection  of  a  line  and  a  page  surface  is  a 
record.  In  most  cases,  the  overprint  dimension  is  very  narrow 
and  very  ragged. 

For  every  line,  each  non-null  overprint  record  is  meshed  into 
the  primary  page  surface  by  pushing  down  all  subsequent  lines, 
including  null  ones.  The  page  is  thus  reduced  to  a  single 
surface.  If  the  depth  of  this  surface  exceeds  the  upper  bound 
of  the  page-depth  dimension,  the  "long  page  handllxig"  datum  of 
the  output  UD  is  queried.  If  this  has  the  value  "trimcate", 
excess  lines  are  discarded.  If  it  has  the  value  "fold",  a  new 
page  surface  is  constructed  of  the  excess  lines,  and  this 
surface  is  placed  behind  the  current  page  by  pushing  all 
subsequent  pages  back  one.  If  it  has  the  value  "leave  as-is", 
the  page-depth  bound  is  effectively  (but  temporarily)  Increased 
to  accomodate  the  long  page. 


i!*l»l** 

Jv*:* 


I  *  f  ^ 


P;:; 


0 


i  •  *.6 


w 


Supporting  the  IBM  File  System  in  NSW 
November  20,  1980  —  Part  II:  FP/360 

PAGE  30 


The  above  procedure  is  implemented  by  replacing  "skip  O"  record 
control  with  "skip  l".  If  page  overflow  occurs,  either  records 
are  discarded  until  the  next  "formfeed"  record  control,  a 
"formfeed"  is  forced  into  an  existing  record,  or  the  situation 
is  simply  ignored. 

2. 1.6. 2. 2.  CONVERTING  3  TO  2 

Each  page  consists  only  of  a  single  surface.  These  surfaces 
have  a  fixed  maximum  line  count,  but  vary  in  actual  line  counts. 
Each  page  is  catenated  to  the  bottom  of  the  previous  page.  If 
the  page  being  catenated  to  has  fewer  than  the  maximum  lines, 
and  if  the  output  LFD  "short  page  handling"  datum  has  the  value 
"pad",  then  null  lines  will  be  inserted  to  bring  the  short  page 
up  to  size. 

In  other  words,  "formfeed"  record  control  is  converted  to  "skip 
n",  where  "n"  is  either  1,  or  1  plus  the  output  page  depth  minus 
the  line  counter. 

2. 1.6. 2. 3.  CONVERTING  2  TO  1 

Each  record  is  catenated  after  the  previous  one,  resulting  in  a 
single  string.  Keys  are  discarded.  IL  record  control  fields  of 
the  form  "skip  n"  are  replaced  by  a  string  of  length  n-l  times 
the  output's  "minimum  text  length"  field,  and  containing  the 
selected  fill  character.  In  practice,  it  is  then  necessary  to 
break  the  resulting  string  into  arbitrary  transmission  block 
strings,  and  prefix  these  with  meaningless  "skip  O"  fields. 

FP/360  will  not  actually  support  this  conversion  in  Version  2. 

2. 1.6. 3.  CASE  CONVERSION 

If  the  "force  upper  case"  option  switch  is  set  for  the  output  file 
type,  and  if  type  translation  is  in  effect  (that  is,  if  the  input 
and  output  file  types  are  not  equal),  then  case  conversion  occurs. 
The  EBCDIC  codes  for  the  lower-case  characters  ("a"  -  "z")  are 
converted  to  those  for  the  upper-case  characters  ("A"  -  "Z").  No 
other  character  codes  are  affected. 

2. 1.6.4.  TRUNCATION  AND  PADDING 

When  type  translation  is  in  effect  (that  is,  if  the  input  and 
output  file  types  are  not  equal),  then  record  and  page  truncation 
and  padding  may  occur.  These  conversions  are  governed  by  the 
indicators  set  in  the  local  file  attributes.  They  are  implemented 
as  described  above  under  "DIMENSIONAL  CONVERSION". 
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2. 1.6.5.  FORMAT  EFFECTOR  EXPANSION 


When  translating  a  file  out  of  IL  representation,  and  in  no  other 
case,  format-effector  conversion  occurs.  This  ccmversion  is 
defined  to  operate  on  those  ASCII  format  effectors  that  the 
encoding  File  Package  has  seen  fit  to  represent  in  the  stream  by 
tokens  of  the  corresponding  explicit  IL  format -effector  type 
codes.  The  data  characters  of  an  IL  stream  are  fully  transparent, 
so  format  effectors  that  have  been  left  in  that  representation  are 
simply  translated  into  their  EBCDIC  equivalents. 

The  ASCII  format  effectors  that  are  converted  are:  form  feed 
(FF) ,  line  feed  (LF) ,  vertical  tab  (VT) ,  horizontal  tab  (HT) , 
backspace  (BS) ,  and  carriage  return  (CR) .  Each  occurrence  of 
these  codes  is  converted  without  regard  to  any  pairing.  It  is  a 
requirement  on  the  encoding  File  Package  that  pairs  of  format 
effectors  that  are  equivalent  in  meaning  to  the  IL  "new  line" 
("skip")  and  "new  page"  record  control  constructs  be  represented 
by  those  constructs. 

Each  format  effector  has  a  corresponding  local  attribute  that 
defines  how  it  is  to  be  expanded.  The  details  of  the  expansion 
are  left  for  a  future  version  of  this  document. 


Supporting  the  IBM  File  System  in  NSV 
November  20,  1980  —  Part  II:  FP/360 

PAGE  32 


2.2.  FP/360  PROGRAM  LOGIC 

FP/360  has  the  overall  structure  shown  in  figure  2.  The  dispatcher 
establishes  process  Instances,  accepts  procedure  calls,  and  selects  a 
procedure  executor.  Each  procedure  executor  is  responsible  for 
decoding  that  procedure's  parameters,  and  usually,  for  completing  the 
main  transaction  by  encoding  appropriate  results.  The  first  action  of 
an  executor  is  thus  to  invoke  the  PL/B8  package  (reference  5)  to 
decode  the  NSWB8  string  contaning  the  parameter  list,  according  to  the 
particular  syntax  of  that  procedure  call. 

Ignoring  for  the  moment  the  trivial  functions,  we  can  describe  FP/360 
as  primarily  a  software  machine  for  executing  a  copy  operation  on  a 
data  file,  possibly  producing  two  outputs  for  a  single  input. 
Following  this  model,  most  of  the  procedure  executors  invoke  a 
"back-end"  coiqmnent  called  the  Basic  Copy  Machine,  or  BCM  (reference 
8),  after  parametrically  tailoring  it  for  the  particular  procedure 
being  executed.  The  BCM  sports  a  variety  of  mode  switches  by  which  it 
can  be  parameterized  to  perform  one  of  at  least  three  basic  copy 
types:  local  copy,  remote  get,  or  remote  send.  Similar  switches 

control  conversion  of  data  among  three  possible  forms:  clear  text, 
IL-encoded,  and  "normalized",  an  intermediate  encodement  internal  to 
the  BCM. 

a 

Because  of  the  complexity  of  the  BCM,  it  is  separately  documented  — 

see  reference  8. 

Further  discussion  of  the  logic  of  FP/360  is  deferred  for  a  future 
version  of  this  document. 
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Figure  2.  FP/360  Structure 
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2.3.  APPENDIX  A:  STATUS  OF  FP/360  IMPLEMENTATION 


2.3.1.  CURRENT  RESTRICTIONS  AND  DEFERRED  FEATURES 

The  following  features  of  the  current  FP  specification  have  not  been 
Implemented,  or  have  been  incorrectly  implemented  in  Version  2  of 
FP/360.  This  list  is  roughly  ordered  by  decreasing  importance 
and/or  increasing  cost  of  Implementation. 

2.3. 1.1.  FORMAT  EFFECTORS 

All  format  effectors  and  record  control  tokens  of  IL  are 
implemented.  However,  those  whose  interpretations  are  defined  in 
the  GFD  (HT,  VT,  LF,  and  FF)  are  supported  only  in  their  interval 
form.  That  is  the  only  form  ever  used  by  the  other  host  families 
that  FP/360  must  support  at  this  time. 

2.3. 1.2.  ALARMS 

FP/360  never  arms  itself  for  alarms,  and  it  never  sends  an  alarm; 
however,  the  status  of  alarms  in  the  current  File  Package 
specification  is  in  flux  anyway.  In  the  meantime,  FP/360  has  no 
mechanism  for  reporting  the  status  of  a  transfer  operation.  If  an 
error  condition  is  found  during  data  transfer,  FP/360  will 
immediately  close  the  connection,  without  sending  the  required 
in-band  normal-eod  signal. 

2.3. 1.3.  ERROR  DESCRIPTORS 

Full  error  descriptors  are  not  supplied  by  FP/360  due  partly  to 
restrictions  in  the  current  version  of  the  PL/PCP  package 
(reference  3),  which  FP/360  uses  for  transaction  management.  In 
particular: 

*  The  optional  parts  of  an  error  descriptor  are  always  null. 

*  Only  one  error  can  be  reported  --  the  first  one  detected. 

*  The  values  of  the  fault  class  and  fault  number  fields  have  not 
been  properly  correlated  with  other  FP  implementations. 

*  An  error  descriptor  received  by  FP/360  from  an  imbedded  SendMe 
transaction  is  not  copied  into  the  reply  that  completes  the  main 
transaction.  The  reply  will  indicate  only  that  an  error 
occurred  in  "SendMe". 
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2.3. 1.4.  STREAM  FILES 

Conversion  to  or  from  one -dimensional  files  is  not  supported. 

2.3. 1.5.  FAMILY  COPIES 

A  format  for  family  copies  of  files  which  caxmot  be  described  in 
IL  has  not  been  defined  for  the  IBM  360  family.  All  network 
transmission  uses  IL. 

2. 3. 1.6.  PASSWORD  PARAMETER 

A  local  data  set  can  be  accessed  by  the  FP  only  if  it  exists 
within  a  directory  in  the  NSW  directory  group  (i.e.,  having  the 
NSW  charge  number) .  Since  there  is  no  mechanism  to  "connect"  to  a 
non -NSW  directory,  the  password  parameter  is  ignored  for  local 
data  seta. 

2. 3. 1.7.  IL  REBLOCKING 

IL  reblocking  is  not  supported;  a  request  to  send  an  IL-encoded 
file  with  a  transmission  block  size  smaller  than  the  IL  blocksize 
in  which  it  is  recorded  on  disk  may  fail.  This  is  not  expected  to 
be  a  problem,  since  IL  block  sizes  are  not  expected  to  vary  in  the 
near  future. 


2.3. 1.8.  BYTE  SIZE 

Only  byte  size  8  is  supported. 

2.3. 1.9.  SUBFILES 

The  "subfile"  facility  of  IL  is  not  supported. 

2.3.1.10.  ANALYZE 

The  FP-ANAL  procedure  call  is  a  no-operation,  and  FP/360  itself 
never  Issues  such  calls. 

2.3.1.11.  PHYSICAL  FORMAT  RESTRICTIONS 

Only  sequential  (DS0RG«PS)  files  are  supported  on  the  360.  In 
particular,  partitioned  (library)  files  are  not  supported,  nor  are 
generation  data  groups. 


y  'iV. 


The  MVT  option  codes  (OPTCD)  are  not  supported. 

Direct  (non-sequentlal)  access  to  a  keyed  data  set  is  not 
supported. 
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2.3.1.12. 


2.3.1.13. 


DEVICE  TYPES 

The  filespace  must  be  on  permanent  lyres  ident  direct-access 
volumes;  tapes  and  removable  disk  packs  are  not  supported. 

HONESTY  CHECKS 

During  translation  or  re-encodement  of  a  file,  FP/360  does  not 
verify  that  the  input  data  conforms  to  the  advertised 
dimensionality.  However,  the  result  created  by  FP/360  will  have 
the  requested  dimensionality,  regardless  of  input.  There  is  one 
major  exception:  if  the  input  and  output  files  are  of  the  same 
type  and  encodement,  then  no  data  Interpretation  occurs  during  the 
copy,  and  no  checki^  of  any  kind  is  done. 
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2.3.2.  FP  SPECIFICATIONS  QUESTIONS 


This  section  lists  design  features  of  FP/360  which  are  at  variance 
with  questionable  or  unsettled  aspects  of  the  official  FP  specs. 
They  are  listed  here  to  draw  attention  to  some  areas  of  uncertainty 
in  the  specifications. 


2. 3. 2.1.  OVERWRITING  EXISTING  DATA 


If  FP/360  is  asked  to  overwrite  an  existing  data  set,  it  will 
delete  the  existing  copy  and  create  a  new  data  set.  This  approach 
has  been  taken  because  there  is  now  no  way  to  avoid  it  and  make 
NSW  work.  However,  we  believe  that  there  are  scenarios  where  this 
destruction  of  existing  data  may  be  an  accident.  One  would  hope  a 
conscientious  WM  would  be  concerned  about  clobbering  data 
accidentally. 


2. 3. 2. 2.  EXPORT  FAILURES 


When  FP/360  Export  is  creating  both  a  primary  (exported)  copy  and 
also  a  secondary  NSW  copy,  it  fails  if  either  copy  fails,  even  if 
the  other  '  copy  could  have  been  created  successfully.  This  could 
waste  an  expensive  and  lengthy  network  transmiss,ion.  We  suggest 
that  the  FP  specifications  be  changed  to  allow  a  partial  success 
in  Export. 


2. 3. 2. 3.  RESULT  LISTS 


In  general,  when  FP/360  encounters  an  error,  it  will  abandon  the 
operation  completely  rather  than  complete  it  partially. 
Therefore,  the  "result  list"  for  the  FP  calls  will  be  null. 
Eventualy,  it  may  be  desirable  to  define  a  restart  mechanism  to 
salvage  partial  file  transfers. 


An  exception  is  the  Delete  operation.  FP/360  will  handle  a  list 
of  deletions,  returning  a  result  list  that  indicates  which  ones 
succeeded  and  which  ones  failed. 


2. 3. 2. 4.  SYNTAX  OF  DELETE 


The  syntax  of  the  Delete  transaction  is  Implemented  according  to 
what  is  now  being  received  from  the  Checkpointer ,  not  according  to 
the  FP  specifications.  The  Checkpointer  is  due  to  be  chenged  in 
the  future. 


2. 3. 2. 5.  READ-ONLY  FILES 


NSW  specifications  state  that  a  tool  may  have  access  to  only  a 
copy  of  an  NSW  file;  however,  there  are  a  number  of  potential  360 
tools  which  are  incapable  of  writing  to  their  input  files,  and 


which  can  be  reliably  expected  not  to  clobber  them.  For  these 
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tools,  ue  need  to  avoid  the  delay  inherent  in  making  an 
unnecessary  copy.  We  now  do  this  using  the  "read-only"  local  file 
attribute,  but  this  method  is  unsatisfactory  both  in  design  and 
implementation.  Ve  need  an  NSW-wide  specification  for  this 
facility. 

2. 3. 2. 6.  AVOIDING  REDUNDANT  LOCAL  COPY 


If  Export  finds  a  local  NSW  copy  of  the  source  file,  it  does  not 
produce  a  new  NSW  copy  even  if  requested  to  do  so.  We  believe 
that  the  FP  specifications  should  state  this. 

2. 3. 2. 7.  ASKING  USER  ABOUT  CONVERSIONS 

When  a  requested  file  conversion  implies  a  non- invertible  change 
of  the  logical  file  contents,  we  wish  to  make  a  HELP  call  to  ask 
the  user's  permission.  This  facility  is  not  presently  available 
to  us,  so  FP/360  assumes  that  the  permission  is  granted.  We 
believe  that  the  HELP  facility  should  be  made  available  to  a  File 
Package  whenever  there  is  a  User  available. 
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2.3.3.  DESIGN  POINTS 

The  following  are  particular  aspects  of  the  FP/360  design  that  we 
believe  to  be  permanent  and  non-controversial.  They  are  listed  here 
just  because  someone  may  want  to  know. 

2.3.3. 1.  FILE  NAMING  CONVENTIONS 

The  catenation  of  the  PCD's  DIRECTORY  and  NAME  fields,  with  a 
period  between,  must  form  an  MVT  DSNAME  of  at  most  44  characters. 

2. 3. 3. 2.  USAGE  OF  PCD  PHYS  FIELD 

The  PHYS  field  of  the  PCD  is  never  examined.  In  locally  created 
PCD's,  it  will  be  a  null  character  string. 

2. 3. 3. 3.  SELECTING  CANDIDATE  FILE  FOR  EXPORT 

Export  will  prefer  input  PCD  candidates  in  this  order: 

1)  a  local  data  set  not  IL-encoded. 

2)  a  local  IL-encoded  data  set. 

3)  a  remote  IL^encoded  file. 

3)  a  remote  file  not  IL-encoded. 

2. 3. 3. 4.  EXPORT  RETRY 

If  FP/360  Export  encounters  a  failure  in  retrieving  a  particular 
physical  copy  of  a  file,  it  will  select  the  next  most  desirable 
copy  from  the  PCD  list  and  try  again.  This  will  continue  until  a 
copy  is  produced,  the  PCD  list  is  exhausted,  or  the  number  of 
retries  exceeds  a  limiting  value  which  is  an  initialization 
parameter . 

2. 3. 3. 5.  UNDEFINED  FORMAT  EFFECTORS 

FP/360  will  support  variable  format  effectors  only  when  they  are 
explicitly  defined  in  the  GFD.  If  such  a  format  effector  occurs 
without  a  GFD  definition,  it  will  simply  be  converted  into  the 
corresponding  EBCDIC  code.  However,  such  codes  are  included  in 
the  EBCDIC  set  only  for  physical  device  control;  they  are  normally 
unacceptable  input  to  360  tools. 
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2.4.  APPENDIX  B:  360  FAMILY  CONVENTIONS 

At  prasant,  FP/360  doas  not  axlst  on  aora  than  ona  host;  tharafora,  no 
actual  intra>360  coHninications  tachniquaa  ara  dafinad.  Tba  Itaas 
balov  ara  only  diractlona  which  aight  davalop  into  family  convantions. 

2.4.1.  All  lina  tranaaiaaion,  avan  faaily  copiaa,  will  probably  uaa  tha  IL 
ancodaaant.  Wa  baliava  that  a  trua  faaily  tranaaiaaion  protocol 
will  bacoaa  uaaful  only  whan  apacial  fila  atructuraa  auch  aa  IBM* a 
Partitionad  Data  Sat  (PDS)  organization  ara  aupportad.  Evan  than, 
wa  would  propoae  to  uaa  a  auparaat  of  IL  aa  tha  faaiily  protocol. 

2.4.2.  Tha  PCD  DIRECTORY  filad  containa  that  part  of  tha  local  data  aat 
naaa  that  corraaponda  to  an  MVT/TSO  LOGON  diractory.  Thia  ia  not 
abaolutaly  conatant  acroaa  MVT  iaplaaantationa ,  ao,  for  the  purpoaa 
of  defining  a  360  faaily  convention,  no  aora  will  be  aaid. 

2.4.3.  The  NAME  field  containa  that  part  of  tha  local  DSNAME  that  ia  not  in 
DIRECTORY.  Tha  DSNAME  ia  forawd  by  catenating  thaaa  two  fialda  with 
a  period  between  thaa. 

2.4.4.  Tha  PCD  ILFLAG  field  ia  tha  only  place  where  FP/360  racorda  or 
diacovara  tha  fact  that  a  local  data  aat  ia  in  IL. 
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APPENDIX  C:  VERSION  2  INITIALIZATION  PARAMETERS 

FP/360  decodes  a  set  of  initialization  parameters  from  a  configuration 
data  set  which  may  optionally  be  supplied  under  file  name  (DDNAME) 
FARMS.  This  data  set  is  in  the  form  of  a  PL/ I  GET  DATA  input  stream. 
The  following  data  may  be  specified,  where  each  name  should  be 
qualified  by  the  name  "P.": 


Name: 

Type: 

Default: 

Meaning: 

NSW_DIRECTORY 

CHAR 

'AHA179.NSW' 

Default  directory  name  for 
creating  a  new  data  set 
in  NSW  filespace. 

NSW_DSN_PAT 

CHAR 

'GEN. NSW?????' 

Default  naaie  used  for 
creating  a  new  data  set 
in  NSW  filespace. 

WSP_0IRECT0RY  CHAR 

'AHA179.NSW’ 

Default  directory  name  for 
creating  a  new  dataset 
outside  NSW  filespace. 

WSP_DSN_PAT 

CHAR 

'GEN.WSP?????' 

Default  name  used  for 
creating  a  new  data  set 
outside  NSW  filespace. 

GENERICNAME 

CHAR 

'FLPKG' 

FP/360 's  MSG  generic  name. 

MSG_TINE0UT 

FIXED 

60,000 

MSG  message  timeout  value, 
in  0.01  seconds. 

PCP_TINE0UT 

FIXED 

600,000 

PCP  transaction  timeout  value, 
in  0.01  seconds. 

HAXCOPIES 

FIXED 

1 

Limit  on  the  number  of  copy 
attempts  within  Export. 

NAX_IL_TRANS 

FIXED 

7286 

Maximum  length  of  an  IL 
transmission  block. 

HAX_BLKSIZE 

FIXED 

7294 

Upper  limit  on  block  size  of 

IL  data  sets. 


(continued) 
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MIN.BLKSIZE 

FIXED 

1000 

Lower  limit  on  block  size  of 
IL  data  sets. 

QfT.ADJUSTMENT  FIXED 

8.0 

Number  of  hours  EARLIER  than 
Greenwich  to  assume  the 
local  clock  to  be  running. 

The  value  may  be  signed 
(for  the  Eastern  hemisphere) 
and  may  carry  the  fraction 
”.0"  or  ”.5"  (for  half- 
hour  time  zones). 

MAXHATERS 

FIXED 

1 

Limit  on  number  of  remater- 
izations  of  process  before 
it  stops. 

NSWVOL 

CHAR 

’NSWPOl’ 

Direct-access  volume  on  which 
to  create  new  data  sets  in 

NSW  file  space. 

VSPVOL 

CHAR 

'NSWPOl' 

Direct-access  volume  on  which 
to  create  new  da^a  sets  in 
a  tool  workspace. 
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APPENDIX  D:  IL  GRAMMAR 


I.  The  File  Transmission  Protocol 

<file-transmission> 

: <transmission-block>  (l:n)  <oot> 
<tranamlssion-block> 

: :=  <byte-count>  <block> 

<byte“Count> 

: unsigned  two  byte  quantity  greater  than  0 

<eot> 

: :=  end  of  transmission,  a  <byte-count>  «  0 

<block> 

: a  block  of  file  bytes,  <byte'‘count>  long 


II.  The  Intermediate  Language  Grammar 
<text-fllea> 

concatenation  <block>  (l:n) 
<text-file8> 

<text-file>  "251” 

I  <subfiles>  "251"  (not  supported) 
<subfiles> 

: <subfile>  (l:p)  (not  supported) 
<subfile> 

: :=  <text-f ile>  "250"  (not  supported) 


III.  File  Records 
<text-flle> 

<tecord>  (0:q) 

<record> 

:  :■  <data->record> 

<data-record> 

: <rec-ctl>  <key>  (0:1)  <item>  (0:s) 


(continued) 
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IV.  Record  control 
<rec-ctl> 

ti224"  I  ••225”  I  ...  I  ”237” 

I  "238"  <nl> 

I  "239"  <n2> 

I  "246"  new  page 

I  <format-eff> 

<nl> 

: unsigned  8-bit  quantity 

<n2> 

: unsigned  16-bit  quantity  formed  by 

concatenating  two  successive  8 -bit  bytes 

<£ormat-eff> 

"242"  (line  feed) 

I  "243"  (vertical  tab) 

1  "244"  (form  feed) 

V.  Keys 

<key>  : :*  <char>  (k) 


VI.  Data  Record  Items 
<item> 

: :=  <string> 

I  <repeat> 

I  <flll> 

I  <special-character> 

<8trlng> 

: <str-len>  <char>  (0:r) 
<repeat> 

: :»  <rep-len>  <char> 

<8tr-len> 

"0"  I  "1"  I  "2"  I  ...  I  "127" 

<fill-len> 

"128"  |  "129"  |  ...  |  "l9l" 

<rep-len> 

: "192"  |  "193"  |  . . .  |  "223" 
<8pecial-character> 

I  "240"  backspace 

I  "24l"  horizontal  tab 

I  "245"  carriage  return 

I  "247"  <ASCII-ctl> 

<ASCII-ctl> 

: an  ASCII  control  character 


(continued) 
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VII.  IL  Types 


PATTERN 

VALUE  RANGE 

MEANING 

Oxxxxxxx 

0  -  127 

string  length  0  :  127 

lOxxxxxx 

128  -  191 

fill  length  0  :  63 

llOxxxxx 

192  -  223 

repeat  length  0  :  31 

lllOxxxx 

224  -  237 

begin  new  record, 
advancing  0-13  records 

11101110 

238 

begin  new  record, 
advancing  0  -  255  records 

11101111 

239 

begin  new  record, 
advancing  0  -  65535  records 

llllOxxx 

240  -  247 

format  effectors 

240 

backspace 

241 

horizontal  tab 

242 

line  feed 

243 

vertical  tab 

244 

form  feed 

245 

carriage  return 

246 

new  page 

247 

ASCII  special  charapter 

lllllOxx 

248  -  251 

subfiles  and  blocking 

248 

reserved 

249 

reserved 

250 

end  of  sub-file 

251 

end  of  IL  transmission 

llllllxx 

252  -  255 

reserved 
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PART  III:  THE  BCM 


BCH  FUNCTIONAL  SPECIFICATIONS 


1.  PURPOSE  AND  CAPABILITIES 

The  Basic  Copy  Machine,  or  BCM,  is  a  CALL* able  program  for  copying 
and  transforming  a  data  stream.  It  was  designed  and  developed  as 
the  main  working  component  of  the  National  Software  Works  (NSW)  File 
Package  program  (reference  1,  2),  and  in  all  aspects  its  design 
facilitates  its  use  in  that  environment.  However,  it  may  be  useful 
in  other  environments  as  well,  and  this  document  is  addressed  to  the 
general  caller  as  much  as  the  File  Package  implementor  and 
maintainer. 

Tile  BCM  may  be  useful  in  any  situation  where  it  is  desired  to  copy  a 
data  set  with  certain  attributes  of  data,  encodement,  and  storage, 
into  a  data  set  with  different  attributes.  The  BCM  is  most  useful 
when  each  of  the  two  sets  of  attributes  corresponds  to  a 
well-defined  native  file  type  that  has  already  been  assigned  a 
"Global  File  Type"  (GFT)  name;  however,  the  user  ftay  also  enumerate 
elementary  attributes.  Sections  of  this  document  will  list 
available  GFT's,  available  elementary  file  attributes,  and  supported 
transformations . 

The  non-NSW  caller  will  see  some  peculiarities  as  a  result  of  the 
BCH's  NSW  orientation.  Notable  among  these  are: 

*  The  BCH  describes  the  formats  of  its  data  files  in  terms  of  the 
NSW's  "Global  File  Type”  (GFT)  names.  The  general  caller  may 
use  a  File-Package-provided  subroutine  to  convert  such  a  type 
name  into  a  set  of  elementary  attributes,  or  he  may  specify 
elementary  attributes  himself.  The  latter  approach  considerably 
complicates  use  of  the  BCH. 

*  The  parametric  interface  to  the  BCM  is  not  compact  or  clean. 
Some  parts  of  it  will  not  concern  the  general  caller. 

*  The  BCM  expects  a  cooperative  and  friendly  caller  which  has  done 
a  reasonable  Job  of  consistency  checking  the  BCH's  input 
parameters.  Thus  the  BCM  is  not  forgiving  of  errors. 

*  The  BCH's  capabilities  for  cross-network  copying  of  data  streams 
are  virtually  unavailable  to  any  caller  except  the  NSW  File 

Package . 
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Figure  1:  Basic  Structure  of  the  BCM 


Data  Regions: 


Copy  Functions: 


Files: 


— .. — .. 
I  INPUT 
I  Region 
_ .... 


**A*li**ilr*****eiHli 

I  *  GET  *<- 

!<.-*  Function  * 
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-0  INPUT  0 
0  File  0 
000000000000000 
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*  Function  * 

************************ 
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*....... _ .....*  **************** 


0000000000000000 
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(arrows  indicate  possible  data  record  flow) 
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3.1.2.  FILES 

The  basic  structure  of  the  BCM  is  shown  in  Figure  1.  The  program 
uses  three  data  files,  each  of  which  has  attributes  associated  with 
an  NSW  GFT  name. 

*  There  is  always  a  primary  input  file.  If  this  is  to  be  a  local 
data  set,  it  is  allocated  to  and  read  through  file  name  (DDNAME) 
INPUT.  It  may  also  be  a  remote  file  on  another  NSW  host. 

*  There  is  an  optional  primary  output  file.  If  this  is  to  be  a 

local  data  set,  the  BCM  will  create  it  (if  it  already  exists  the 

old  copy  may  have  to  be  deleted  first)  and  write  it  through  file 
name  WSPOUT.  It  may  also  be  a  remote  file  on  another  NSW  host. 
The  data  written  through  this  file  may  be  reformatted  if  the 
file  is  assigned  a  different  GFT  from  the  input  file. 

*  There  is  an  optional  secondary  output  file.  If  it  is  used,  it 

must  be  a  local  data  set,  and  it  must  have  the  same  GFT  as  the 

input  file. 

The  BCM  also  uses  routine  MSGJOUR,  of  the  PL/MSG  s.ubroutine  package, 
to  write  informative  messages  to  the  user.  This  routine,  unless 
instructed  otherwise  (see  the  documentation  for  PL/MSG),  will  write 
to  QSAH  output  file  MSGJOUR,  if  such  a  file  is  allocated.  If  it  is 
not  allocated,  no  harm  is  done.  If  the  program  is  executing  in  the 
foreground,  MSGJOUR  will  also,  unless  instructed  otherwise,  write 
its  output  to  the  controlling  TSO  terminal  via  TPUT.  There  is  an 
option  to  also  write  the  output  to  another  TSO  terminal,  if  the 
named  userid  is  logged  on  (reference  3) . 

Since  the  BCM  is  written  in  PL/I  (for  the  IBM  Optimizing  Compiler), 
it  can  conceivably  write  diagnostic  messages  from  the  PL/I  numi^ 
system.  These  normally  require  a  file  named  SYSPRINT.  It  is 
advisable  to  allocate  such  a  file  Just  in  case  of  errors. 
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3.1.3.  DATA  TRANSFOBMATIONS 

<  The  primary  output  file  emits  the  data  from  the  input  file  after 

applying  any  required  transformations.  These  may  include: 

*  Trans forsiat ion  into  a  compressed  form.  The  coiiq>ression  scheme 
used  is  that  defined  for  NSW  Intermediate  Language  (IL); 
however,  EBCDIC  to  ASCII  translation  can  be  suppressed,  and  the 
various  ASCI I -oriented  format  effectors  that  can  be  expressed  in 
IL  are  never  generated  by  the  BCM. 

*  E]q>ansion  from  the  cospressed  form.  The  various  ASCII-oriented 
format  effectors  that  can  be  expreased  in  IL  can  be  expanded  or 
converted  to  EBCDIC  control  characters.  ASCII  to  EBCDIC 
translation  can  be  suppressed. 

*  Dimensional  conversion  among: 

(a)  TWo-dimensional  data  --  lines  or  records. 

(b)  Three-dimensional  data  --  lines  organized  into  pages. 

(c)  Four-dimensional  data  --  overprinted  ,  records  organized 
into  lines,  and  optionally  further  organized  into  pages. 

*  Generating,  stripping,  or  interpreting  ASA  carriage  control. 
Note  that  when  processing  carriage  control  or  format  effectors 
of  any  kind,  the  BCM  must  make  an  initial  assumption  about  the 
virtual  position  of  the  output  file  before  any  positioning  is 
performed.  This  is  always  assumed  to  be  on  the  non-existent 
line  Just  preceedlng  the  first  line  of  the  data  space,  with  the 
horizontal  position  left  tmdefined. 

*  Generating,  stripping,  or  moving  sequence  number  fields. 

*  Truncating  or  folding  long  records  or  pages. 

*  Forcing  upper  case. 

*  Stripping  trailing  fill  characters  (blanks  for  text  data,  binary 
zeros  for  binary  data). 

*  Changing  the  OS/ 360  RECiM,  LkECL,  and  BLKSIZE. 
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3.1.4.  OPERATING  ENVIRONMENTS 

The  BCM  executes  under  IBM  OS/360  MVT,  in  the  environment  provided 
by  the  PL/I  Optimizing  Compiler's  execute-time  library.  The  BCM  can 
operate  in  either  the  foreground  or  the  background. 


*  FOREGROUND  OPERATION  --  The  BCM  is  most  at  home  operating  in  the 
foreground,  under  the  TSO  Terminal  Monitor  Program  (IMP).  File 
allocation  operations  are  handled  by  the  TSO  DAIR  routine, 
through  UCLA's  PLIDAIR  package  (reference  4). 

*  BACKGROUND  OPERATION  —  The  BCM  will  operate  in  the  OS/360 
background  environment  provided  appropriate  substitutes  for  the 
PLIDAIR  entries  named  ALLOC,  CREALL,  FREE,  and  DELETE  are 
provided.  If  file  allocation  operations  are  handled  external  to 
the  BCM  (as  through  Job  Control  Language  statements),  these  may 
be  stubs  that  return  zero  status  codes.  Renamed  copies  of 
routine  FMNULL  can  be  used  (see  the  section  entitled  USEFUL 


SUPPORT  ROUTINES) . 

The  BCM  can  operate  as  either  a  local  copy  machine  or  a  network  copy 
machine,  with  some  restrictions  in  the  latter  mode. 

*  LOCAL  OPERATION  --  If  the  input  and  output  streams  of  the  BCM 
are  local  data  sets,  then  its  use  is  essentially  unrestricted. 
The  caller  will  need  to  set  certain  parametric  data  to 
prescribed  values  in  order  to  avoid  actuating  the  network 
communications  machinery.  He  may  delete  certain  BCM  subroutines 
that  effect  such  communication,  if  the  BCM  is  to  be  included  in 
his  load  module  directly. 

*  NETWORK  OPERATION  --  If  either  the  input  or  the  output  of  the 
BCM  is  not  a  local  data  set,  then  the  BCM  performs  certain 
restricted  network  procedure  calls.  These  calls  will  fail 
unless  the  BCM  caller  has  already  established  himself  as  a 
legitimate  NSW  process  of  class  "FLPKG".  Further  details  of 
this  mode  of  operation  can  be  found  in  the  section  entitled 
"SPECIAL  REQUIREMENTS  FOR  NETWORK  COPIES". 
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BCM  FILES 

The  BCM's  actual  input  and  output  streams  may  require  the  allocation 
of  files  named  INPUT  (the  input  stream),  WSPOUT  (the  primary  output 
stream) ,  and  NSWOUT  (the  secondary  output  stream) .  Other  functions 
use  files  named  SYSPRINT  (PL/I  diagnostics),  HSGJOUR  (optional 
journaling  output),  and  PARMS  (optional  parameters  •-  see  the 
section  entitled  FPINIT  —  ALTER  DEFAULT  VALUES). 
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3.2.  BCM  USER'S  MANUAL 


This  section  is  addressed  to  the  BCM  user  —  that  is,  to  the 
programmer  who  is  writing  a  program  to  call  the  BCM. 


3.2.1.  CALLING  THE  BCM 


Conceptually,  the  BCM  is  called  as: 


BCM  (  input  file  description, 

primary  output  file  description, 
secondary  output  file  description, 
environment  description, 
default  values  table  ) 

-->  (  error  description, 

primary  output  data  set  description, 
secondary  output  data  set  description  ) 


The  actual  PL/I  call  looks  like  this: 


DECLARE  FPCOPY  ENTRY  (POINTER,  POINTER,  POINTER,  POINTER); 
CALL  FPCOPY  (  AOOR  (envlronment_descriptor) , 

ADDR  (input_file_descriptor) , 

ADDR  (prlmary_output_f ile_descriptor) , 

ADDR  (secondary_output_f ile_descriptor)  ) ; 
^INCLUDE  source_library  (DDFAULT); 


where  results  are  returned  in  descriptors,  and  the  "default  values 
table"  is  provided  as  a  static  external  data  structure.  The 
descriptors  are  described  in  the  next  sections. 
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Figure  2;  The  BCM  Data  Region  Descriptor 


3  REC  CONTROL,  /*  POINTS  TO  CURRENT  REC.  */ 

4  (TEXTAD,  KEYAD)  POINTER, 

4  (LNGTEXT,  LNGKEY,  SKIPS)  FIXED  BIN(15), 

3  FILENAME  CHAR (8)  VAR,  /*  DDNAME,  TITLE  OPTION.  */ 

3  REALFILE  FILE,  /*  POINTS  TO  FILE  CONSTANT  */ 

3  PCD, 

4  HOST, 

5  NUMBER  FIXED  BIN(15),  /*  NETWORK  HOST  ADDRESS.  */ 


S  NAME  CHAR(32)  VAR,  /*  HOST  MNEMONIC  NAME.  */ 

5  FAMILY  CHAR(32)  VAR,  /*  HOST  FAMILY  NAME.  */ 

5  RELATI(»4  FIXED  BIN(15),  /*  LOCAL,  FAMILY,  FOREIGN  */ 

4  DIRECTORY  CHAR(56)  VAR,  /*  FIRST  PART  OF  NAME.  */ 

4  FNAME  CHAR(56)  VAR,  /*  SECOND  PART  OF  NAME.  */ 

4  PHYS  POINTER,  /*  PHYSICAL  ENCODE.  INFO.  */ 

4  IL  ENCODED  BIT(l),  /*  TRUE  -->  COPY  IN  IL.  */ 

3  FUD,“  /*  file  USAGE  DESCR;  */ 

4  APPROX  BIT  COUNT  FIXED  BIN(31),  /*  TOTAL  IL  SIZE.  */ 

4  ACTUAL"BL0CKSIZE  FIXED  BIN(IS),  /*  TO  BE  USED  */ 

4  BUFFER^SIZE  FIXED  BIN(IS),  /*  FOR  ALLOCATION.  */ 

4  PASSWORD  CHAR(32)  VAR,  /*  ACCESS  PASSWORD  */ 

4  DSNAME  CHAR(56)  VAR,  /*  FULL  DATA  SET  NAME.  */ 

4  USAGE  FIXED  BIN(15),  /*  OLD  OR  NEW  */ 

3  GLOBAL  TYPE  CHAR(32)  VAR,  /*  GLOBAL  TYPE  NAME  */ 

3  TYPE  DESCRIPTOR, 

4  TYPE  TYPE  FIXED  BIN(15),  /*  NATIVE/FAMILY/FOREIGN  */ 

4  GFD,“  /*  global  FILE  DESCR:  */ 

5  CLASS  FIXED  BIN(15),  /*  1— >TEXT,  2— >BINARY.  */ 

5  KEYLENGTH  FIXED  BIN (15),  /*  0  — >  NO  KEYS.  */ 

5  DIMENSION  FIXED  BIN(15),  /*  1  TO  4.  */ 

5  BYTESIZE  FIXED  BIN(15),  /*  USUALLY  8  ...  */ 

5  HTAB,  I*  HORIZONTAL  TABS...  */ 

6  (ILCHAR,  EBCCKAR)  CHAR(l), 

6  (INCREMENT,  STOPCOUNT,  ST0PS(20))  FIXED  BIN(IS), 

5  VTAB,  /*  VERTICAL  TABS...  */ 

6  (ILCHAR,  EBCCHAR)  CHAR(l), 

6  (INCREMENT,  STOPCOUNT,  ST0PS(20))  FIXED  BIN(15), 

5  IF,  /*  LINEFEED...  */ 

6  (ILCHAR,  EBCCKAR)  CHAR(l), 

6  (INCREMENT,  STOPCOUNT,  ST0PS(20))  FIXED  BIN(15), 

5  FF,  /*  FORMFEED...  */ 

6  (ILCHAR,  EBCCKAR)  CHAR(l), 

6  (INCREMENT,  STOPCOUNT,  STOPS(20))  FIXED  BIN(IS), 


(Continued) 


Supporting  the  IBM  File  System  in  NSW 
November  20,  1980  --  Part  III:  BCM 

PAGE  10 


Figure  2  (continued):  The  BCM  Data  Region  Descriptor 


4  LFD,  /*  LOCAL  FILE  DESCR:  */ 

5  DIMENSIONAL_PREFERENCE  (4)  FIXED  BIN(15), 

5  TEXT_LNG, 

6  (MAX,  MIN)  FIXED  BIN(15), 

5  COMP  FACTOR  FIXED  BIN (15), 

5  KEY_OFFSET  FIXED  BIN (IS), 

5  FOLD_MARGIN  FIXED  BIN(15), 

5  PAGE_DEPTH  FIXED  BIN(15), 

5  HANDLING_OF, 

6  (KEYS,  L0NG_REC0RDS,  SHORT_RECORDS ,  LONG  PAGES, 

SHORT_PAGES,  HTAB,  VTAB,  LF,  FF,  BSP,  CR)  FIXED  BIN(IS), 
5  OPTIONS, 


6  (FORCE_UPPER,  SUPPRESS_TRANSLATE ,  SUPPRESS_EXPAND, 
KEEP_FILLS,  INPUT_ONLY)  BIT(l)  ALIGNED, 


4  PSD, 

/*  DEFAULT  PHYS  STRUCTS. 

*/ 

5  DSORG  CHAR (6)  VAR, 

/*  DATA  SET  ORGANIZATION. 

*/ 

5  RECFM  CHAR(6)  VAR, 

/*  RECORD  FORMAT. 

*/ 

5  OPTCD  CHAR(6)  VAR, 

/*  OPTION  CODES. 

*/ 

5  LRECL  FIXED  BIN (15), 

/*  LOGICAL  RECORD  LENGTH. 

*/ 

5  BLKSIZE, 

/*  BLOCKSIZE. 

*/ 

6  (MAX,  MIN)  FIXED  BIN(IS), 

5  KEYLEN  FIXED  BIN (IS), 

/*  RECORDED  KEY  LENGTH. 

*/ 

5  RKP  FIXED  BIN(15), 

/*  RECORDED  KEY  OFFSET. 

*/ 

5  SPACE  ALLOCATION, 

6  (PRIMARY,  SECONDARY, 

PDSDIR)  FIXED  BIN(15), 

3  VOLUME  CHAR(6)  VAR, 

/*  FOR  CREATING  NEW  DS'S. 

*/ 
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3 . 2 . 1 . 1 .  BUILDING  THE  INPUT  FILE  DESCRIPTOR 

The  BCM  input  file  descriptor  is  one  of  the  BCM  "Data  Region 
Descriptors",  as  defined  by  ^INCLUDE  segment  DDFILE  and 
illustrated  in  Figure  2.  This  structure  is  used  both  as  input 
parameters  and  as  internal  working  storage  by  the  BCM.  Which 
fields  must  be  preset  by  the  caller  depends  on  whether  the  input 
is  remote  or  local. 

3. 2. 1.1.1.  FOR  LOCAL  INPUT 


*  HOST. RELATION  -■>  Set  to  zero  (the  local  system). 

• 

*  DIRECTORY  and  FNAME  —  These  two  fields,  when  concatenated 
with  a  period  between  them,  form  the  local  OSNAME,  which  must 
be  fully  qualified,  but  not  quoted,  and  without  a  member  name 
or  generation  number.  The  data  set  thus  identified  must 
already  exist.  Neither  field  should  be  blank  or  null. 

*  IL^ENCODED  Set  this  bit  to  'O'B  unless  the  input  file  is 
already  encoded  in  NSW  IL  compressed  form.  , 

*  6L0BAL_TYPE  Set  this  to  one  of  the  NSW  GFT  names.  Since 
this  is  a  local  file,  this  string  will  normally  begin  with 
"360-". 

*  GLOBAL_TYPE_DESCRIPTOR  --  Set  this  entire  substructure  by 
calling  routine  FPDGTYP  (see  the  section  entitled  USEFUL 
SUPPORT  ROUTINES),  passing  the  address  of  the  entire  file 
descriptor.  Field  GLOBAL_TYPE  must  have  been  already  set 
before  calling  FPDGTYP.  If  the  value  of  GL0BAL_TYPE  does  not 
begin  with  "360-",  then  follow  the  instructions  for  remote 
input  files,  just  below. 

*  PASSWORD  --  Processing  of  this  field  is  deferred  for  now.  Set 
it  to  a  null  string. 


I 

i 

I 
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3.2. 1.1.2.  FOR  REMOTE  INPUT 

If  the  BCM  caller  is  dealing  with  a  remote  input  file,  it  is 
assumed  that  he  has  access  to  the  NSW  data  structures  normally 
used  to  describe  such  files. 


*  HOST. NUMBER,  .DIRECTORY,  .FNAME,  .PHYS,  and  .IL_ENCODED  —  Set 
these  fields  directly  from  the  PCD  of  the  remote  file  copy 
selected. 

*  HOST. NAME  and  .FAMILY  --  These  fields  are  only  used  to  format 
error  messages,  and  they  can  be  set  to  null  strings.  You  can 
set  them  more  aesthetically  by  calling  routine  MSGHTYP  (see 
the  section  entitled  USEFUL  SUPPORT  ROUTINES),  passing 
HOST. NUMBER. 

*  HOST. RELATION  --  Set  this  to  1  (family  host)  if  the  remote 
host  is  another  360-compatible  system,  or  to  2  (foreign  host) 
otherwise.  If  you  have  called  routine  MSGHTYP,  you  can  look 
for  the  string  "360"  in  field  HOST. FAMILY  to  decide  this. 
When  in  doubt,  it  is  safe  to  assume  a  foreign  host  type. 

*  PASSWORD  —  Set  this  field  to  whatever  text  string  serves  as  a 
security  key  to  permit  access  to  the  remote  file.  If  the 
remote  system  does  not  use  passwords,  set  this  field  to  a  null 
string.  In  normal  File  Package  operation,  this  datum  will 
have  been  given  the  File  Package  by  its  caller. 

*  GL0BAL_TYPE  --  Set  this  to  the  NSW  GFT  name  associated  with 
the  remote  file  copy. 

*  GLOBAL_TYPE_DESCRIPTOR  --  Set  this  entire  structure  by  calling 
routine  FPDGTYP  (see  the  section  entitled  USEFUL  SUPPORT 
ROUTINES),  passing  the  address  of  the  entln  file  descriptor, 
field  GLOBAL_TYPE  must  have  been  already  set  before  calling 
FPDGTYP.  If  the  string  in  GLOBAL_TYPE  does  not  begin  "360-", 
then  you  must  also  set  all  values  of  substructure  GFD  (either 
before  or  after  calling  FPDGTYP).  Most  of  these  fields  can  be 
copied  directly  from  the  GFD  of  the  NSW  file  being  accessed. 
The  exceptions  are  the  four  fields  named  EBCCHAR.  These 
should  contain  the  EBCDIC  codes  for  Tab  (decimal  5),  Vertical 
Tab  (11),  Line  Feed  (37),  and  Form  Feed  (12).  If  you  must 
generate  GFD  information  yourself,  see  the  section  entitled 
DEFINING  FILE  ATTRIBUTES  for  assistance. 
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3. 2. 1.2.  BUILDING  THE  PRIMARY  OUTPUT  FILE  DESCRIPTOR 

The  BCM  primary  output  file  descriptor  is  one  of  the  BCM  "Data 
Region  Descriptors",  as  defined  by  %INCLUDE  segment  DDFILE  and 
Illustrated  in  figure  2.  This  structure  is  used  both  as  input  and 
output  parameters  and  as  internal  working  storage  by  the  BCM. 
Which  fields  must  be  preset  by  the  caller  depends  on  whether  the 
primary  output  is  remote,  local,  or  null. 

3. 2. 1.2.1.  FOR  LOCAL  PRIMARY  OUTPUT 


*  USAGE  set  to  3  (a  transformed  output  file) . 

*  HOST. RELATION  --  Set  to  zero  (the  local  system). 

*  DIRECTORY  and  FNAME  These  two  fields,  when  concatenated 

with  a  period  between  them,  form  the  local  DSNAME,  which  must 
be  fully  qualified,  but  not  quoted,  and  without  a  member  name 
or  generation  number.  If  DIRECTORY  is  null,  the  value  of 
WSP_0IRECT0RY  in  the  default  values  table  will  be  used.  If 
FNAME  is  null,  the  value  of  WSP_DSN_PAT  in  the  defalut  values 
table  will  be  used.  However  it  is  generated,  the  resulting 
DSNAME  may  contain  up  to  7  "?"  characters.  Tliese  will  be 

replaced  by  p8eudo'*’zandomly  chosen  alphanumeric  (not 
alphabetic)  characters  to  generate  a  unique  name  (different 
substitutions  will  be  tried  until  the  generated  name  does  not 
match  any  existing  data  set). 

If  the  data  set  name  contains  wild  characters,  and  if  every 
possible  substitution  for  those  characters  yellds  a  name  which 
matches  that  of  an  existing  data  set,  then  the  copy  operation 
will  fall.  However,  if  the  name  does  not  contain  wild 
characters,  and  if  a  data  set  of  that  name  already  exists,  the 
BCM  will  delete  the  old  copy  and  recreate  it  according  to  the 
attributes  associated  with  this  copy  operation. 

*  IL_ENCODED  *-  Set  to  'o'B  unless  the  primary  output  file  is  to 
be  encoded  in  NSW  IL  compressed  form. 

*  GLOBAL_TYPE  —  Set  this  to  one  of  the  NSW  GFT  names.  Unless 
IL_ENCODED  is  'I'B,  the  name  chosen  must  begin  with  "360-”. 

*  GLOBAL_TYPE_DESCRIPTOR  **'  Set  this  entire  structure  by  calling 
routine  FPDGTYP,  passing  the  address  of  the  entire  file 
descriptor.  Field  GLOBAL_TYPE  must  be  already  set  before 
calling  FPDGTYP.  If  the  value  of  GLOBAL_TYPE  does  not  begin 
with  "360-",  then  follow  the  Instructions  below  for  remote 
output  files. 
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PASSWORD  --  Processing  of  this  field  is  deferred  for  now. 
it  to  a  null  string. 


Set 
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3. 2. 1.2. 2.  FOR  REMOfTE  PRIMARY  OUTPUT 

If  the  BCM  caller  is  dealing  with  a  remote  primary  output  file, 

it  is  assumed  that  he  has  access  to  the  NSW  data  structures 

normally  used  to  describe  such  files. 

*  USAQI  --  set  this  field  to  3  to  indicate  a  transformed  output 
file. 

*  HOST. NUMBER  *-  Set  this  field  to  the  NSW  host  number  of  the 
remote  host.  Normally,  this  will  have  been  learned  from  an 
incoming  FP-SENDME  call  from  that  host. 

*  HOST. NAME  and  .FAMILY  — >  These  fields  are  only  used  to  format 
error  messages,  and  they  can  be  set  to  null  strings.  You  can 
set  them  more  aesthetically  by  calling  routine  MS6HTYP  (see 
the  section  entitled  USEFUL  SUPPORT  ROUTINES).  passing 
HOST.NUMBER. 

*  HOST. RELATION  ••  Set  this  to  1  (family  host)  if  the  resiote 
host  is  another  360-compatible  system,  or  to  2  (foreign  host) 
otherwise.  If  you  have  called  routine  MSGHTYP,  you  can  look 
for  the  string  **360**  in  field  HOST. FAMILY  to  decide  this. 
When  In  doubt,  it  is  safe  to  assume  a  foreign  host  type. 

*  PASSWORD  --  Set  this  field  to  whatever  text  string  serves  as  a 
security  key  to  permit  access  to  the  remote  file.  If  the 
remote  system  does  not  use  passwords,  set  this  field  to  a  null 
string.  In  normal  File  Package  operation,  this  datum  will 
have  been  given  the  File  Package  by  its  caller. 

*  8L0BAL_TYPE  --  Set  this  to  the  NSW  GFT  nasM  to  be  associated 
with  the  remote  file  copy. 

*  GL0tAL_TYPE_DI8CR I PTOt  —  Set  this  entire  structure  by  calling 
routine  FPDGTYP  (see  the  section  entitled  USEFUL  SUPPORT 
lOOTINES),  passing  the  address  of  the  entire  file  descriptor. 
Field  OLOBAL^TYPE  must  have  been  already  set  before  calling 
FPOGTYP.  If  the  string  in  GLOBAL_TYPE  does  not  begin  "360-", 
them  you  oust  also  set  all  values  of  substructure  GFD  (either 
before  or  after  calling  FPOGTYP) .  Moat  of  these  fields  can  be 
copied  directly  from  the  GFD  of  the  NSW  file  being  accessed. 
Tbs  exertions  are  the  four  fields  named  EBCCHAR.  These 
should  contain  the  EBCDIC  codes  for  Tab  (decimal  5),  Vortical 
Tab  (11),  Line  Feed  (37),  and  Form  Feed  (12).  If  you  must 
generate  GFD  information  yourself,  see  the  section  entitled 
DEFINING  FILE  ATTRIBtniS  for  assistance. 
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*  IL_ENCODED  —  Set  this  bit  to  *l’B. 
FOR  NULL  PRIMARY  OUTPUT 


If  no  primary  output  is  desired,  siiiq>ly  set  USAGE  to  zero  (null 
usage) . 
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3.2. 1.3.  BUILDING  THE  SECONDARY  OUTPUT  FILE  DESCRIPTOR 

The  BCM  secondary  output  file  descriptor  is  one  of  the  BCM  "Data 
Region  Descriptors",  as  defined  by  %INCLUDE  segment  DDFII£  and 
illustrated  in  figure  2.  This  structure  is  used  both  as  input  and 
output  parameters  and  as  internal  working  storage  by  the  BCH.  The 
output  must  be  either  null  or  to  a  local  data  set. 

3.2. 1.3.1.  FOR  LOCAL  SECONDARY  OUTPUT 


*  USAGE  --  set  this  field  to  2  to  indicate  an  untransformed  copy 
of  the  input  file. 

*  HOST. RELATION  -**  Set  to  zero  to  Indicate  the  local  system. 

*  DIRECTORY  and  FNAME  These  two  fields,  when  concatenated 

with  a  period  between  them,  form  the  local  DSNAME,  which  must 
be  fully  qualified,  but  not  quoted,  and  without  a  member  name 
or  generation  number.  If  DIRECTORY  is  null,  the  value  of 
NSW_0IRECT0RY  in  the  default  values  table  will  be  used.  If 
FNAME  is  null,  the  value  of  NSW_DSN_PAT  in  the  defalut  values 
table  will  be  used.  However  it  is  generated,  the  resulting 
DSNAME  may  contain  up  to  7  "?”  characters.  These  will  be 

replaced  by  pseudo-randomly  chosen  alphanumeric  (not 
alphabetic)  characters  to  generate  a  unique  name  (different 
substitutions  will  be  tried  until  the  generated  name  does  not 
match  any  existing  data  set). 

If  the  data  set  name  contains  wild  characters,  and  if  every 
possible  substitution  for  those  characters  yeilds  a  name  which 
matches  that  of  an  existing  data  set,  then  the  copy  operation 
will  fail.  However,  if  the  name  does  not  contain  wild 
characters,  and  if  a  data  set  of  that  name  already  exists,  the 
BCH  will  delete  the  old  copy  and  recreate  it  according  to  the 
attributes  associated  with  this  copy  operation. 

*  1L_ENC0DED  Copy  this  datum  from  the  input  file  descriptor. 

*  GL0BAL_TYPE  and  GLOBAL_TYPE_DESCRIPTOR  —  Copy  these  data  from 
the  input  file  descriptor. 

*  PASSWORD  --  Processing  of  this  field  is  deferred  for  now.  Set 
it  to  a  null  string. 

3.2. 1.3.2.  FOR  NULL  SECONDARY  OUTPUT 

If  no  secondary  output  is  desired,  simply  set  USAGE  to  zero 

(null  usage). 


mi 
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3. 2. 1.4.  BUILDING  THE  ENVIRONMENT  DESCRIPTOR 

The  BCM  Environment  Descriptor  is  a  structure  of  the  form  defined 
by  %INCIiUDE  segment  DDPCPFMT  and  illustrated  in  Figure  3.  The 
primary  purpose  of  this  descriptor  is  to  communicate  the  status  of 
the  NSW  Procedure  Call  Protocol  (PCP)  environment  (reference  5)  to 
those  portions  of  the  BCM  which  must  do  network  communications. 
It  is  also  used  to  comoiunicate  an  error  code  and  string  back  to 
the  BCM  caller.  Only  the  latter  function  is  of  concern  if  the 
copy  is  to  be  local. 

3 . 2 . 1 . 4 . 1 .  FOR  LOCAL  COPY  OPERATIONS 


«***»>*. 
y  »*>  •  , 


w 

pi 


If  the  BCM  is  operating  only  on  local  datasets,  only  two  fields 
are  of  concern. 

*  ERROR_TYPE  --  preset  this  field  to  zero. 

*  ERROR_STRING  ->  preset  this  field  to  a  null  string. 

3.2. 1.4.2.  FOR  NETWORK  COPY  OPERATIONS 

If  the  BCM  is  operating  on  any  remote  file,  th.un  the  caller  must 
be  using  the  PL/PCP  package  (reference  5). 


I 

W 


*  MASTER_ECB  --  this  word  must  have  been  passed  to  PCBEGIN  as 
the  PCP  master  ECB. 

*  LOCAL  PROCESS  '•*  Store  the  local  process  handle  returned  from 
PCBEGIN  here. 


V'Vv 


*  CALLER  Store  the  process  handle  of  the  calling  process 
here. 

*  CALL  --  Store  the  transaction  handle  of  the  call  being 
executed  here. 


m 

[K:* 


*  ERROR_TYPE  --  preset  this  field  to  zero. 

*  ERROR_STRING  preset  this  field  to  a  null  string. 


I 


V'Vi*7v' 
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Figure  3:  The  BCM  Environment  Descriptor 


2  MASTER  ECB  FIXED  BINARY(31),  /*  FOR  TPEXAM  CALLS  */ 

2  LOCAL  PROCESS  POINTER.  /*  TO  A  PROCESS  STRUCTURE  */ 

2  CALL^  POINTER.  f*  TO  REMOTE  PROCESS  STRUCT  */ 

2  CALL  POINTER.  /*  TO  TRANSACTION  STRUCTURE  */ 

2  CALL  TYPE  CHAR(6) .  /*  FROM  TPEXAM  */ 

2  TERM”RECEIVED  BIT(1).  /*  MSG'S  "TS"  SETS  THIS  */ 

2  ERROR  TYPE  FIXED  BIN(15).  /*  FROM  "FPERRNO"  */ 

2  REPLY'STRING  CKAR(255)  VAR.  /*  PROCEDURE  RESULTS  */ 

2  ERROR'^STRING  CHAR(2S5)  VAR.  f*  ONLY  VARIABLE  ?hXT..,  */ 

2  VORKB8.  /*  PL/B8  WORK  AREA  &  RC  */ 

3  B8  RETURN_CODE  FIXED  BIN(31). 

3  VORKAREA  (35)  FIXED  BIN(31); 


Figure  4:  The  BCM  Default  Values  Table 


DECLARE  1  DOFAULT  STATIC  EXTERNAL. 

2  MSG  TIMEOUT  FIXED  BINARY(31)  INIT  (60000). 

2  PCP~TIMEOUT  FIXED  BINARY(31)  INIT  (1800000), 
2  IMP~ TIMEOUT  FIXED  BINARY(31)  INIT  (60000) . 

2  MAXC0PIE8  FIXED  BIN  (15)  INIT  (1). 

2  MAXMATER8  FIXED  BIN  (15)  INIT  (1). 

2  GMT  ADJUSTMENT  FIXED  BIN(15,4)  INIT(8.0), 

2  MAX'BLKSIZE  fixed  BIN(15)  INIT(7294), 

2  MIN'BLKSIZE  fixed  BIN(15)  INIT(IOOO). 

2  NAX~IL  TRANS  FIXED  BIN(15)  INIT(7286), 

2  (NSW  DIRECTORY  INIT('AHA179.NSW' ) . 

NSW  DSN  PAT  INrr('GEN.NSW77?77'), 
WSP~DIRiCTORT  INIT('AHA179.NSW'), 

WSP“D8N  pat  INIT('caN.WSP77777’)) 

~  ~  CKAR(44)  VAR. 

2  GENERICNAME  C11AR(16)  VAX  INIT('FLPKG' ) . 

2  NSWVOL  CHAR(6)  INIT('NSWPOl' ) . 

2  WSPVOL  CHAR(6)  INIT( 'NSWPOl' ) . 

2  VERIFY  IMPORT  BIT(l)  INIT(OB); 
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BUILDirra  THE  DEFAULT  VALUES  TABLE 

The  BCM  Default  Values  Table  is  a  structure  of  the  form  defined  by 
XINCLUDE  segment  DDFAULT  and  illustrated  in  Figure  4.  You  must 
include  this  structure  somewhere  in  the  load  module  that  calls  the 
BCM.  XINCLUDE  segment  DDFAULT  will  set  default  values  in  the 
structure;  however,  your  program  can  alter  any  of  these  prior  to 

calling  the  BCM.  You  can  also  call  routine  FPINIT  (see  the 

section  entitled  USEFUL  SUPPORT  ROUTINES),  which  will  execute  a 
"GET  DATA"  on  the  entire  structure,  thus  allowing  execute-time 
changes  by  the  program  user.  The  structure  is  designed  to  provide 
default  values  for  the  NSW  File  Package  program,  so  many  of  the 

fields  are  not  used  by  the  BCM.  Those  which  are  are: 

*  PCPTIMEOUT  —  If  the  BCM  must  issue  an  FP-SENDME  call  to 
another  network  host,  this  value  is  used  for  the  PCCALL  timeout. 

*  MAX_BLRSIZE  and  MIN_BLKSIZE  --  These  values  are  used  as  the 
bounds  in  selecting  a  device-dependent  block  size  for  a  local 
output  data  set  to  hold  IL  compressed  data. 

*  MAX  IL  TRANS  -•  The  maximum  length  of  a  ne.twork  transmission 
block.” 

*  NSW_DIRECT0RY  —  The  string  to  be  used  if  the  DIRECTORY  field  of 
the  secondary  output  descriptor  is  null. 

*  N8W_D8N_PAT  --  The  string  to  be  used  if  the  FNAME  field  of  the 
secondary  output  descriptor  is  null.  This  should  contain  at 
least  one,  but  not  more  than  seven,  "7”  characters. 

*  WSP.DIRECTORY  —  The  string  to  be  used  if  the  DIRECTORY  field  of 
the  primary  output  descriptor  is  null. 

*  W8P_D8N_PAT  —  The  string  to  be  used  if  the  FNAME  field  of  the 
primary  output  descriptor  is  null.  This  should  contain  at  least 
one,  but  not  more  than  seven,  "7”  characters. 

*  NSV^VOUMI  --  The  name  of  the  local  filespace  voliime  on  which 
secondary  output  data  sets  are  to  be  created. 

*  WSP^VOLUMC  The  name  of  the  local  filespace  volume  on  which 
priatary  output  data  sets  are  to  be  created. 
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5:  BCM  Error  Codes 


string: 


GFT  name 


GFT  name 


DSNAHE 


DSNAHE 

OSNAME 


DSNAHE 


meaning: 

No  error. 

One  of  the  BCM  File  Descriptors  is  invalid 
or  inconsistent. 

An  internal  error  has  prevented  the  encoding 
of  a  network  message  a  BCM  bug  is  probably 
indicated. 

An  I/O  error  occurred  in  reading  or  writing 
one  of  the  BCM  files.  Network  and  local 
device  errors  are  treated  the  same. 

The  BCM  is  transmitting  a  file  already 
encoded  in  IL  to  a  remote  host.  A  record 
in  the  input  file  is  longer  than  the  value 
of  MAX  IL  TRANS  in  the  Default  Values 
Table." 

A  record  to  be  transformed  in  to  the 
indicated  GFT  format  has  a  data  portion 
greater  than  LFD  TXT  LNG.MAX,  and  the 
value  of  LFD.HANDLIN6_0F.L0NG_REC0RDS 
indicates  that  this  is  an  error. 

The  input  file  does  not  have  keys,  and 
the  output  GFT  indicates  in  field 
LFD. HANDLIN6_0F. KEYS  that  the  output 
file  snist  have  non^generated  keys. 

An  output  file  descriptor  specifies 
values  of  DIRECTORY  and  FNAHE  that 
isap  into  the  name  of  an  existing  data 
set.  If  there  are  ”7"  characters  in 
the  name,  all  possible  permutations 
snd  conbinations  of  alphanumeric 
substltuends  yeild  such  duplicate 
names. 

An  I/O  error  occurred  during  data  set 
creation. 

There  is  no  file  space  which  both  has 
sufficient  room  to  crest  the  output 
data  set,  and  is  legally  accessible  by 
the  File  Package. 

An  unknown  error  occurred  during  data 
set  creation. 


(Continued) 
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Figure  5  (Continued):  BCM  Error  Codes 


26 


Host  name 


27 


28 


29 


The  BCM  is  negotiating  with  the  remote 
host  which  owns  its  input  file.  The 
negotiating  network  transaction  failed, 
probably  due  to  a  timeout  as  specified  by 
PCP_TIME0UT  or  MSG_TIMEOUT  of  the  Default 
Values  Table. 

The  BCM  is  negotiating  with  the  remote 
host  which  owns  its  input  file.  That 
host  has  returned  an  unintelligible 
message. 

The  network  connection  to  a  remote  host 
cannot  be  opened  by  PL/MSG.  If  the 
PL/MSG  LOG  option  is  being  used,  the 
messages  written  to  file  MSGJOUR  may 
have  more  information. 

The  network  connection  to  a  remote  host 
cannot  be  closed  by  PL/MSG.  If  the 
PL/MSG  LOG  option  is  being  used,  the 
messages  written  to  file  MSGJOUR  may 
have  more  information. 
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3.2. 1.6.  RETRIEVING  BCM  RETURNED  VAUJES 

The  BCM  returns  values  in  several  places  in  its  parameter 
structures : 

3.2. 1.6.1.  PRIMARY  ERROR  CODE 

Field  ERROR_TYPE  of  the  Envimonment  descriptor  will  contain 
zero  if  the  copy  completed  normally,  and  non-zero  otherwise. 
Field  ERR0R_STRING  will  be  either  null  or  a  string  suitable  for 
inserting  into  an  error  message.  Figure  5  lists  possible  error 
codes,  their  meanings,  and  suggested  error  messages  with 
insertion  points  for  the  variable  string. 

3 . 2 . 1 . 6 . 2 .  GENERATED  DATA  SET  DESCRIPTORS 

If  no  error  occurred,  the  primary  and  secondary  output  file 
descriptors  will  have  certain  fields  filled  in  to  describe  any 
local  data  sets  actually  created  from  within  the  BCM.  Note  that 
if  you  fool  the  BCM  into  thinking  that  it  has  created  a  data  set 
when  the  data  set  was  actually  created  previously,  these  values 
will  be  meaningless.  See  the  section  eivtltled  FMNULL  -- 
BYPASSING  PLIDAIR  for  more  infoirmation  on  this  mode  of 
operation. 

*  DSNAME  --  This  field  will  contain  the  fully  qualified,  quoted, 
data  set  name  actually  assigned  the  output  data  set.  All  ”?" 
characters  will  have  been  replaced  by  alphanumerics . 

*  ACTUAL_BIiKSIZE  —  This  field  will  contain  the  block  size 
actually  selected  for  the  data  set. 

*  PSD  --  All  subfields  of  this  substructure  except  for  the 
BLKSIZE  substructure  indicate  the  actual  values  used  to  create 
the  data  set. 
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3.2.2.  USEFUL  SUPPORT  ROUTINES 


Several  routines  of  various  NSV-related  packages  can  be  used  by  the 
BCM  caller  to  some  advantage: 


3.2.2. 1.  FPDGTYP  —  DEFINE  GLOBAL  TYPE 


Routine  FPDGTYP  fills  in  substructure  TYPE_DESCRIPTOR  based  on  the 
value  of  field  GLOBAL_TYPE  (see  Figure  2).  It  is  called  by: 


DECLARE  FPDGTYP  ENTRY  (POINTER,  FIXED  BIN  (IS)); 
CALL  FPDGTYP  (  ADDR  (file_desctiptor) ,  error_code); 


where : 


"file__descrlptor"  is  a  BCM  "Data  Region  Descriptor",  as  defined 
by  %INCLUDE  segment  DDFILE  and  Illustrated  in  Figure  2.  Field 
GL0BAL_TYPE  must  already  be  filled  in. 


"error_code"  is  returned  as  zero  after  a  norma^l  operation  or  as 
non-zero  if  GLOBAL  TYPE  contained  a  native  but  unknown  GTF 


Three  cases  exist: 


If  "error_code"  is  non-zero,  then  the 
nothing  else  will  have  been  filled  in. 


is  illegal. 


If  "error_code"  is  zero  and  field  TYPE_TYPE  is  zero,  then 
the  GFT  is  a  known  native  type,  and  all  fields  of 
TYPE  DESCRIPTOR  have  been  filled  in. 


If  "error_code"  is  zero  and  field  TYPE_TYPE  is  non-zero, 
then  the  GFT  is  an  unknown  type,  and  has  been  assummed  to  be 
valid  but  non-native.  Substructure  GFD  has  not  been 
altered,  and  the  rest  of  TYPE_DESCR1PT0R  has  been  filled  in 
with  values  that  describe  the  preferred  method  of  storing 
non-native  IL-encoded  data  sets  on  the  360  system.  Before 
calling  the  BCM,  you  must  fill  in  all  values  of  GFD  (either 
before  or  after  calling  FPDGTYP) .  In  the  normal 
network-transfer  case,  the  BCM  caller  will  already  be 
holding  GFD  data  received  from  his  caller.  For  other  cases, 
refer  to  the  section  entitled  DEFINING  FILE  ATTRIBUTES  for 
assistance. 
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FPDGTYP  uses  File  Package  subroutines  FPERKNO  and  FPGTTAB. 
FPGTTAB  is  loaded  dynamically,  so  it  must  be  made  available 
through  one  of  the  mechanisms  available  to  program  fetch 
(previously  loaded,  Linkpack,  Linklib,  JOBLIB,  STEPLIB,  Task 
library,  etc.)* 
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3. 2. 2. 2.  FPINIT  —  ALTER  DEFAULT  VALUES 


Routine  FPD6TYP  can  be  called  to  allow  modification  of  the  default 
values  table  by  the  program  user.  It  is  called  by: 


DECLARE  FPINIT  ENTRY  (FILE,  *), 

FARMS  STREAM  INPUT  FILE; 
IINCLUDE  source_llbrary  (DDFAULT); 
CALL  FPDGTYP  (  FARMS,  DDFAULT  ); 


FPINIT  issues  a  "GET  DATA"  against  its  input  file,  which  it  opens 
to  file  name  FARMS,  and  its  input  structure,  which  it  calls  P. 
Thus  an  example  of  valid  file  input  to  FPINIT  might  be: 


//FARMS  DD  * 

P.PCP  TIMEOUT  =  40000, 
P.WSPVOL  «  'WKSPC2'  : 


FPINIT  will  function  normally  with  or  without  the  semicolon 
normally  used  to  terminate  data*directed  input.  It  will  act  as  a 
no-operation  routine  if  no  FARMS  file  is  allocated. 
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3. 2. 2. 3.  FMNULL  —  BYPASSING  PLIDAIR 

FMNULL  is  an  Assembler  subroutine  that  merely  locates  its  last  (or 
returning)  parameter  cell,  stores  a  halfword  of  zeros  there,  and 
returns.  Thus  it  can  be  substituted  for  any  entry  of  either  of 
the  forms: 


DECLARE 

routine 

ENTRY 

( 

...  ) 

RETURNS 

(FIXED  BIN  (15)); 

or 

DECLARE 

routine 

ENTRY 

( 

...  ,  error_code) 

error_code  FIXED  BIN  (15); 


Since  all  entries  of  the  PLIDAIR  package  are  of  this  form,  FMNULL 
can  be  substituted  at  Linkage-Edit  time  for  entries  ALLOC,  CREALL, 
FREE,  and  DELETE.  This  makes  the  BCM  bypass  all  file-allocation 
operations.  That,  it  turn,  makes  the  BCM  exeputable  in  a  batch 
environment,  where  its  files  are  defined  by  JCL  statments  of  the 
form: 


//INPUT  DD  <define  the  input  file> 

//WSPCUT  DD  <define  the  primary  output  file> 
//NSWOUT  DD  <define  the  secondary  output  file> 


However,  the  BCM  caller  must  understand  that  the  data  set  names 
and  characteristics  that  are  returned  by  the  BCM  in  its  file 
descriptors  are  not  meaningful  in  this  case. 
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3. 2. 2. 4.  MSGHTYP  —  FINDING  HOST  RELATIONSHIPS 

When  the  BCM  is  operating  in  its  network  mode,  it  is  necessary  to 
classify  the  remote  host  system.  Routine  MSGHTYP  can  do  this.  It 
is  a  part  of  the  NSW  PL/MSG  subroutine  package,  and  is  thus 
documented  elsewhere  (reference  3).  Parsimoniously  put,  its 
calling  sequence  is: 


DECLARE  MSGHTYP  ENTRY  (FIXED  BIN  (15), 

CHAR  (32)  VAR.  CHAR  (32)  VAR);  ! 

DECLARE  1  file_descr,  i 

^INCLUDE  source_library  (DDFILE);  ! 

CALL  MSGHTYP  (file_descr. HOST. NUMBER,  /*  you  preset  */  I 

file_descr. HOST. NAME,  /*  returned  */  • 

file_descr. HOST. FAMILY);  /*  returned  */  I 


I 


-  a  r  K  •  o  V'- )» 
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3.2.3.  DEFINING  FILE  ATTRIBUTES 

The  simplest  way  to  use  the  BCM,  and  the  way  that  is  recommended,  is 
to  assign  a  complete  set  of  attributes  to  each  file  in  the  form  of 
an  NSW  GFT  name.  These  names  are  then  converted  to  a  set  of  file 
attributes  by  subroutine  FPDGTYP  (see  the  section  entitled  USEFUL 
SUPPORT  ROUTINES).  If  no  GFT  name  exists  that  properly  defines  your 
file  type,  it  may  be  that  such  a  name  should  be  added;  see  local  NSW 
maintenance  personnel. 

However,  if  your  requirements  are  unique,  then  you  can  build  the 
entire  file  attribute  descriptor  substructure  yourself.  You  begin 
by  constructing  a  BCM  Data  Region  Descriptor  using  ^INCLUDE  packet 
DDFILE,  illustrated  in  Figure  2.  Fields  GLOBAL  TYPE  and 
TYPE_DESCRIPTOR.TYPE_TYPE  are  not  examined  by  the  BCM  (except  that 
GLOBAL_TYPE  may  be  moved  into  ERROR_STRING  of  the  Environment 
Descriptor  under  certain  circumstances)  so  you  need  not  set  them; 
however,  most  of  substructures  GFD  (the  Global  File  attribute 
Descriptor),  LFD  (the  Local  File  attribute  Descriptor),  PSD  (the 
Physical  Structure  Descriptor)  must  be  set. 

It  is  important  to  understand  that  values  for  certain  attributes  are 
often  required  by  the  BCM  even  when  they  do  not  appear  to  have 
meaning  for  the  particular  data  type.  This  is  because  they  may  be 
needed  to  perform  a  type  conversion  into  that  type  from  a  non-native 
type  about  which  no  attributes  are  known.  For  example,  a  "page 
depth '  is  tabulated  for  a  two-dimensional  data  type  if  conversion  of 
non-native  three-dimensional  data  into  that  type  could  occur,  even 
though  page  depth  has  no  meaning  for  a  two-dimensional  file. 

*  GFD. CLASS  --  This  field  determines  whether  the  data  consists  of 
characters  (CLASS  =  1)  or  binary  bytes  (CLASS  =  2),  with  the 
following  consequences : 

(1)  Character-class  data  represents  an  array  of  ASCII  graphics 
of  dimensionality  between  1  and  4  (see  the  discussion  of 
dimensionality  below).  A  full  complement  of  format 
effectors  is  defined  for  use  in  positioning  graphics  within 
the  array.  Unspecified  array  positions  are  assumed  to 
contain  the  fill  character  "blank",  which  is  also  used  for  i 

optimal  compression  in  IL.  > 

Data  dimensionality  of  2  or  higher  is  orgfuiized  into  j 

records  ,  which  may  include  character-string  keys.  A 
common  of  these  keys  will  be  to  record  "sequence  ' 

numbers"  associated  with  text  lines  by  some  text  editors, 
compilers,  and  other  such  programs.  • 

i 

1 

! 
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(2)  Binary-class  data  is  of  dimensionality  1  or  2,  representing 
either  a  single  byte  string  or  a  sequence  of  (short)  byte 
strings  called  "records",  respectively.  There  are  no  format 
effectors  other  than  record  separators.  In  two-dimensional 
data,  a  record  sMy  include  a  character-string  key  as  well  as 
the  binary  text. 

For  binary-class  data,  the  "fill"  character  used  for  optimum 
compression  in  IL  is  a  byte  of  binary  zero. 

GFD.KEYLENGTH  —  This  field  declares  the  width  of  the  key  (or 
sequence  number)  field  associated  with  each  data  record.  A  value 
of  sero  means  that  no  key  field  exists.  Keys  are  always  character 
strings,  even  in  binary-class  files. 

GFD. DIMENSION  --  This  field  declares  the  file  data  to  represent  1, 
2,  3,  or  4  disMnsions.  This  concept  is  defined  as  follows: 

(1)  (At  this  writing,  the  BCM  does  not  yet  support 

oae-dlsMnsional  files.)  One-dimensional  data  consists  of  a 
stream  of  b]rtea  (or  characters)  that  are  not  logically 
grouped  into  lines  or  records.  The  single  dimension 
corresponds  to  file  size,  and  is  effect ive.ly  unbounded. 

(  BTTE  I  c  1,  c»  1  to  file_size  ) 

For  character-class  files,  regular  horizontal  format 

effectors  (see  Figure  2)  are  possible,  but  no  other  format 
effectors  would  be  meaningful.  The  data  may  be  broken 
arbitrarily  into  record- like  strings  for  convenience  in 
handling,  but  it  is  understood  that  these  strings  are  not 
logical  records.  A  one -dimensional  file  cannot  have  keys. 

(2)  TWo-dinenaional  data  consists  of  a  stream  of  bytes  (or 

characters)  divided  into  records  or  lines.  Keys  are 
permitted,  and  if  they  appear  there  is  a  key  included  with 
each  record.  The  first  dimension  is  bounded  by  the  "Record 
Length  Range"  datum  of  the  LFD,  but  the  second  corresponds 
to  file  size,  and  is  effectively  unbounded. 

{  KEY  [  k,  r  ],  BYTE  [  c,  r  ], 

for:  c«  1  to  max-record-text -length, 

k"  1  to  key-width, 
r«  1  to  record-count,  } 

For  character -class  files,  it  is  possible  to  define  any  kind 
of  regular  horizontal  format  effectors  and  regular  vertical 
Interval  format  effectors,  but  no  other  kinds  are 
meaningful . 
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(3)  Three-dimensional  data  consists  of  a  stream  of  characters, 
grouped  into  lines,  which  are  then  grouped  into  pages.  The 
first  dimension  is  bounded  by  the  "Record  Length  Range" 
datum  of  the  LFD,  and  the  second  by  the  "page  depth"  datum, 
but  the  third  corresponds  to  file  size,  and  is  effectively 
unbounded . 

{  KEY  (  k,  r.  p  ],  BYTE  [  c,  r,  p  ], 

for:  c*  1  to  max-record-text-length, 

k*  1  to  key-width, 
r*  1  to  page-depth, 
p*  1  to  page-count  } 

Only  character-class  data  can  be  three-dimensional,  and  it 
is  meaningful  to  define  all  regular  fonsat  effectors.  Keys 
are  legal,  but  will  probably  be  rare. 

(4)  Four-dlsmnaional  data  consists  of  a  stream  of  characters, 
groiqied  into  records,  which  are  then  grouped  into  lines, 
which  may  then  be  grouped  into  pages.  The  first  dimension 
is  bounded  by  the  "Record  Length  Range"  datum  of  the  LFD, 
and  the  second  corresponds  to  overprinting  and  is  unbounded. 
The  third  dimension  is  bounded  by  "page  depth",  while  the 
fourth  corresponds  to  file  size  snd  is  also  unbounded. 

{  KEY  t  k,  r.  1,  p  J,  BYTE  (  c,  r,  1,  p  ], 

for:  c**  1  to  max-record-text- length, 

k"  1  to  key-width, 
r«  1  to  max-overprint -depth, 

1  to  page-depth, 
p*  1  to  page-count  } 

Only  text-class  data  can  be  four-dimensional,  and  it  is 
meaningful  to  define  all  regular  and  irregular  format 
effectors.  Keys  are  legal,  but  will  probably  be  rare. 


GFD.BYTESIZE  --  The  BCH  can  only  process  files  consisting  of  8-bit 
bytes,  so  this  datum  should  be  set  to  8. 

6FD.HTAB,  .VTAB,  .LF,  and  .FF  —  These  substructures  tell  the  BCH 
how  to  expand  the  ASCII-type  format  effectors  that  can  be 
expressed  in  IL-compressed  text.  Whether  these  instructions  are 
used  at  all  depends  on  the  settings  of  switches  in  substructure 
UD . HANDLING_0F ,  described  later. 
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The  names  stand  for  Horizontal  Tab,  Vertical  Tab,  Line  Feed,  and 
Form  Feed,  respectively.  The  functions  performed  by  these  format 
effectors  are  handled  in  other  ways  in  a  360-compatible  system, 
and  these  other  ways  also  have  IL  representations.  Therefore,  the 
BCM  itself  never  generates  such  format  effectors  when  doing  IL 
compression,  and  the  only  time  it  can  encounter  these  forms  is 
when  it  is  expanding  a  file  that  was  compressed  by  another  NSW 
host  system.  If  you  cannot  be  sure  that  format  effectors  will  not 
be  encountered,  but  you  wish  them  to  have  minimum  significance, 
then  set  these  values  this  way  (all  values  are  decimal): 


substructure: 


field: 

ILCHAR 

1  HTAB 

1  VTAB 

LF 

1 

FF 

1  241 

1  243 

242 

1 

1 

1 

244 

EBCCHAR 

1  5 

1  11 

37 

1 

1 

1 

12 

INCREMENT 

j  1 

1  1 

1 

1 

1 

1 

1 

STOPCOUNT 

1  0 

0 

0 

1 

1 

0 

Otherwise,  three  cases  can  exist  for  each  format  effector.  The 
ILCHAR  and  EBCCHAR  fields  will  always  be  set  the  same,  but  the 
values  of  the  other  fields  vary  as  follows: 

(1)  If  the  format  effector  is  to  remain  undefined,  set  both 

INCREMENT  and  STOPCOUNT  to  zero.  In  this  case,  if  an 

occurrence  of  the  format  effector  is  found  during  the  copy 
operation,  it  will  be  replaced  by  its  EBCDIC  equivalent,  the 
value  of  EBCCHAR. 

(2)  If  the  format  effector  is  defined  to  have  regularly  spaced 
"stops"  in  coltimn  (line)  1  and  in  every  "n"  columns  (lines) 
thereafter,  set  INCREMENT  to  "n"  and  STOPCOUNT  to  zero. 

(3)  If  the  format  effector  is  defined  to  have  a  specific  set  of 
"stops",  set  INCREMENT  to  zero,  STOPCOUNT  to  the  number  of 
such  stops  (maximum  of  20),  and  vector  STOPS  to  the 
(1-orlgin)  values  of  the  stops  themselves.  Unused  elements 
of  STOPS  need  not  be  initialized.  If,  during  the  copy 
operation,  an  occurrence  of  the  format  effector  is  found  to 
lie  beyond  the  column  (line)  indicated  by  the  last  used 
element  of  STOPS,  it  will  be  replaced  by  its  EBCDIC 
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equivalent,  the  value  of  EBCCHAR. 

*  LFD.DIMENSIONAL_PREFERENCE  --  This  datum  defines  a  preference 
ordering  of  the  four  dimensionalities  for  situations  where 
dimensional  conversion  may  be  required.  It  consists  of  a  vector 
of  four  numbers,  corresponding  to  dimensionalities  1  through  4. 
Each  number  consists  of  the  siun  of  two  parts:  First,  an 

Indication  of  whether  conversion  from  that  dimension  is  permitted, 
with  values: 

(000)  Used  for  the  dimension  which  requires  no  conversion. 

(256)  Permit  the  conversion  from  this  dimension. 

(512)  Permit  this  conversion  only  if  interactive  user  approval  can 
be  obtained. 

(768)  Forbid  conversion  from  this  dimension. 

Second,  a  preference  part  simply  ranking  this  dimensionality  in 
terms  of  its  relative  preference  compared  to  another 
dimensionality  with  the  same  first-part.  This  part  can  take 
values  from  0  to  255.  For  example,  if: 


DIMENSIONAL_PREFERENCE  (1)  = 
DIMENS IONAL_PREFERENCE  (2)  = 
DIMENSIONAL_PREFERENCE  (3)  = 
DIMENS IONAL_PREFERENCE  (4)  = 


768; 

/*  Forbid 

*/ 

0; 

/*  No  conversion 

*/ 

?57; 

/*  permit  and  prefer 

*/ 

2  8; 

/*  prefer  only  after 

3  */ 

Then  the  order  of  preference  in  selecting  a  file  to  transform  into 
this  file  type  is  2  (most  preferred),  3,  and  4  (least  preferred), 
with  conversion  from  dimesionality  1  strictly  forbidden. 

*  LFD . TXT_IiNG . MAX  and  .MIN  --  These  two  fields  give  the  maximum  and 
minimum  number  of  bytes  of  data  (exclusive  of  keys)  that  a  record 
of  this  type  can  contain.  This  must  be  compatible  with 
GFD.KEYLENGTH,  PSD.RECFM,  and  PSD.LRECL. 

*  LFD . C0MP_F ACTOR  --  Set  this  field  to  the  estimated 

IL-compressibility  of  typical  data  of  this  type,  as  an  integer 
percentage.  For  example,  "75"  would  mean  that  an  IL  file  of  this 
type  typically  occupies  3/4  as  much  disk  space  as  its  uncompressed 
equivalent . 
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*  LFD . KEY_OFFSET  --  Set  to  the  1-origin  index  of  the  data  byte 
before  which  the  sequence  number  field  appears  in  the  record.  For 
example,  "l"  means  leading  sequence  numbers,  and  "73"  would 
position  the  sequence  numbers  as  for  a  standard  IBM  card-image 
file. 


*  IiFD.FOLD_MARGIN  --  If  it  is  ever  necessary  to  break  a  long  input 
record  into  two  output  records  to  comply  with  LTD . TEXT_LNG . MAX , 
the  continuation  record  may  be  offset  after  a  leading  blank  field. 
Set  this  datum  to  the  1-origin  column  in  which  continuation  data 
is  actually  to  begin.  For  example,  "l"  will  not  offset  the 
continuation  record  at  all. 


*  LFD . PAGE_DEPTH  --  Set  this  field  to  the  number  of  lines  (not 
records)  to  a  printer  page. 

*  LFD . HANDLING_OF . KEYS  --  How  to  generate  missing  keys.  Values  are: 
(0)  Simply  delete  the  key  field. 

(1)  Blank  fill  the  key  field. 

(2)  Generate  sequence  numbers  by  counting  records. 

(3)  The  file  must  have  a  real,  information-bearing  key  field. 
Refuse  to  process  an  input  file  type  that  does  not. 

*  LFD . HANDLING_OF . L0NG_REC0RDS  --  How  to  handle  input  records  with 
more  data  bytes  than  permitted  by  LFD . TEXT_LNG . MAX .  Values  are: 

(0)  Simply  truncate  the  record. 

(1)  Fold  the  record  --  that  is,  make  a  continuation  record 
beginning  in  the  column  specified  by  LFD.FOLD_MARGIN. 

(2)  Call  the  situation  an  unrecoverable  error. 

*  LFD . HANDLING_OF . SH0RT_REC0RDS  --  How  to  handle  input  records  with 
fewer  data  bytes  than  permitted  by  LFD . TEXT_LNG . MIN .  Values  are: 


(0)  Pad  the  record  with  fill  characters. 

(1)  Try  to  Ignore  the  problem. 

*  LFD . HANDLING_OF . LONG_PAGES  --  How  to  handle  input  pages  with  more 
lines  than  permitted  by  LFD . PAGE_DEPTH .  Values  are: 


(0) 


Truncate  the  page. 


Supporting  the  IBM  File  System  in  NSW 
November  20,  1980  --  Part  III:  BCM 

PAGE  35 


(1)  Fold  the  page  --  that  is,  make  it  into  two  pages. 

(2)  Ignore  the  problem. 

LFD.HANDLING_OF.SHORT_PAGES  --  How  to  handle  input  pages  with 
fewer  lines  than  required  by  LFD . PAGE_DEPTH .  Values  are: 

(0)  Pad  out  the  page  with  blank  lines. 

(1)  Ignore  the  problem. 

LID . HANDLING_OF . HTAB  --  How  to  expand  the  IL  encodement  of  the 
ASCII  Horizontal  Tab  format  effector,  if  it  is  encountered  in  the 
input  file.  Values  are: 

(0)  Substitute  an  EBCDIC  Horizontal  Tab  code. 

(1)  Expand  according  to  the  GFD.HTAB  substructure  of  the  BCM's 
Input  File  Descriptor. 

(2)  Expand  according  to  the  GFD.HTAB  substructure  of  the  BCM's 
Primary  Output  File  Descriptor. 

LFD . HANDLING_OF . VTAB  --  How  to  expand  the  IL  encodement  of  the 
ASCII  Vertical  Tab  format  effector,  if  it  is  encountered  in  the 
input  file.  Values  are: 

(0)  Substitute  an  EBCDIC  Vertical  Tab  code. 

(1)  Expand  according  to  the  GFD.VTAB  substructure  of  the  BCM's 
Input  File  Descriptor. 

(2)  Expand  according  to  the  GFD.VTAB  substructure  of  the  BCM's 
Primary  Output  File  Descriptor. 

LFD.HANDLING_OF.LF  --  How  to  expand  the  IL  encodement  of  the  ASCII 
Line  Feed  format  effector,  if  it  is  encountered  in  the  input  file. 
Values  are: 

(0)  Substitute  an  EBCDIC  Line  Feed  code. 

(!''  Expand  according  to  the  GFD.LF  substructure  of  the  BCM's 

Input  File  Descriptor. 

(2)  Expand  according  to  the  GFD.LF  substructure  of  the  BCM's 

Primary  Output  File  Descriptor. 

FFD.HANDLING_OF.FF  --  How  to  expand  the  IL  encodement  of  the  ASCII 
Form  Feed  format  effector,  if  it  is  encountered  in  the  input  file. 
Values  are: 
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(0)  Substitute  an  EBCDIC  Form  Feed  code. 

(1)  Expand  according  to  the  GFD.FF  substructure  of  the  BCM’s 

Input  File  Descriptor. 

(2)  Expand  according  to  the  GFD.FF  substructure  of  the  BCM's 

Primary  Output  File  Descriptor. 

*  LFD.HANDLING_OF.BSP  --  How  to  expand  the  IL  encodement  of  the 

ASCII  Backspace  format  effector,  if  it  is  encountered  in  the  input 
file.  Values  are: 

(0)  Suustitute  an  EBCDIC  Backspace  code. 

(1)  Interpret  as  a  destructive  backspace  order.  That  is,  delete 
the  previous  character,  if  tht..e  is  one. 

(2)  Interpret  as  a  non-destructive  backspace  order.  That  is, 
move  the  "cursor"  back  one  position,  if  that  is  possible, 
but  do  not  delete  any  characters,  and  do  not  shorten  the 
output  record. 

*  LFD . HANDLING_0F . CR  --  How  to  expand  the  IL  encodement  of  the  ASCII 
Carriage  Return  format  effector,  if  it  is  encountered  in  the  input 
file.  Values  are: 

(0)  Substitute  an  EBCDIC  Carriage  Return  code. 

(1)  Interpret  as  a  destructive  carriage  return  order.  That  is, 

delete  ail  characters  previously  placed  in  the  current 
record. 

(2)  Interpret  as  a  non-destructive  carriage  return  order.  That 

is,  move  the  "cursor"  back  one  to  the  beginning  of  the 

current  line,  but  do  not  delete  any  characters,  and  do  not 
shorten  the  output  record. 

*  LFD . OPTIONS . FORCE_UPPER  --  If  this  bit  is  set,  the  characters  of 
the  data  are  to  be  translated  into  all  upper  case. 

*  LFD. OPTIONS. SUPPRESS_TRANSLATE  --  If  this  bit  is  set,  then  IL  data 
of  this  type  is  to  be  considered  to  be  already  in  EBCDIC. 

*  LFD . OPTIONS . SUPPRESS_EXPAND  --  If  this,  bit  is  set,  then  this  type 
represents  data  the  dear-text  format  of  which  is  the  same  as  the 
IL-compressed  format.  This  bit  is  not  processed  by  the  BCM. 

*  LFD. OPTIONS. KEEP_FILLS  --  If  this  bit  is  set,  then  trailing  fill 
characters  in  records  are  considered  to  be  significant. 
Otherwise,  they  can  be  stripped  without  loss  of  information. 


»  ^>..1  \  ^  ^  \  '-"W  ’-“W  w'X 
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*  LFD. OPTIONS. INPUT. ONLY  --  If  this  bit  is  set,  then  data  declared 
to  be  of  this  type  is  to  be  considered  to  be  read-only.  This  bit 
is  not  processed  by  the  BCM. 

*  PSD.DSORG  --  the  recommended  data  set  orgainization  for  creating 
new  files.  The  BCM  only  supports  physical  sequential  data,  so 
this  field  should  contain  the  value  "PS". 

*  PSD.RECFM  --  the  recommended  record  format.  The  BCM  supports: 

F[B[S] ] [A] [T]  (fixed-length  records) 

V[Bj [sj [A] [T]  (variable-length  records) 

^[^1 [T]  (undefined- length  records) 

*  PSD.OPTCD  --  Data  management  option  codes.  The  BCM  merely  copies 
these  into  the  data  set  label,  so  anything  acceptable  to  OS/360  is 
acceptable  here. 

*  PSD.LRECL  --  The  logical  record  length.  This  must  be  compatible 
with  the  values  of  GFD . KEYLENGTH  and  LFD.TXT_LNG. 

*  PSD.BLKSIZE.MAX  and  .MIN  --  The  bounds  on  physical  block  size. 
The  BCM  may  choose  a  value  within  this  range  which  is  compatible 
with  PSD.RECFM  and  PSD.LRECL,  and  which  optimizes  space 
utilization  on  the  selected  physical  device.  If  the  two  values 
are  the  same,  then  no  variation  in  block  size  is  allowed. 

*  PSD.KEYLEN  --  Length  of  random-access  retrieval  key.  The  BCM 
merely  copies  this  into  the  data  set  label.  No  random  retrieval 
is  ever  done  in  the  BCM  itself. 

*  PSD.RKP  --  The  offset  of  the  random-access  retrieval  key  within  a 
record.  The  BCM  merely  copies  this  into  the  data  set  label.  No 
random  retrieval  is  ever  done  in  the  BCM  itself. 

*  PSD. SPACE_ALL0CATI0N. PRIMARY  --  The  recommended  initial  space 
allocation  value,  in  selected  blocksize  units,  to  be  used  if  no 
better  file-size  data  is  available. 

*  PSD. SPACE_ALL0CATI0N. SECONDARY  --  The  recommended  incremental 
space  allocation  value,  in  selected  blocksize  units. 

*  PSD.SPACE_ALLOCATION.PDSDIR  --  The  recommended  number  of  256-byte 
blocks  to  allocate  for  a  partioned  data  set  (PDS)  directory. 
Since  the  BCM  does  not  yet  support  PDS's,  this  value  should  be 
zero. 
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3.2.4.  SPECIAL  REQUIREMENTS  FOR  NETWORK  COPIES 

In  order  to  use  the  BCM  for  network  operations,  the  caller  must  be 
familiar  with  the  operation  of  an  NSW  File  Package,  and  with  the 
mechanisms  for  implementing  such  a  process  at  UCLA.  He  must  have 
already  materialized  an  MSG  process  of  class  "FLPKG”,  using  the 
PL/PCP  subroutine  package  (reference  5).  The  BCM  environment 
descriptor  must  accurately  describe  the  PL/PCP  environment  (see  the 
section  entitled  BUILDING  THE  ENVIRONMENT  DESCRIPTOR) . 

If  the  BCM  input  is  remote,  then  the  BCM  will  invoke  procedure 
FP'SENDME  of  any  FLPKG  process  on  the  indicated  remote  host,  using 
routines  PCCALL  and  PCEXAM. 

If  the  BCM  primary  output  is  remote,  then  the  BCM  will  assume  that 
its  caller  is  responding  to  an  FP-SENIHIE  procedure  call  from  the 
indicated  remote  host,  and  that  field  CALL  of  the  environment 
descriptor  is  a  handle  on  that  transaction.  The  BCM  will  then 
complete  the  transaction  using  routine  PCREPLY. 

Theoretically,  the  BCM  can  copy  a  reomte  input  file  to  a  remote 
output  file;  however,  such  a  request  is  never  generated  in  the  NSW 
system,  so  in  practice,  it  will  not  be  explicitly  .supported. 
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3.3.  BCM  MAINTENANCE  MANUAL 

This  section  is  addressed  to  those  responsible  for  updating  arid 
maintaining  the  BCM  package.  It  describes  the  logical  flow  of  the 
machine  and  the  logical  responsibilities  of  the  various  submodules. 

3.3.1.  BASIC  STRUCTURE 

The  basic  structure  of  the  BCM  is  illustrated  in  Figure  1.  It 
consists  of  a  machine  with  three  external  files,  one  input  and  two 
output,  emd  three  internal  "Data  Regions",  each  associated  with  one 
of  the  files.  During  BCM  execution,  data  records  move  from  the 
input  file,  through  each  of  the  internal  Data  Regions  in  turn,  and 
to  the  output  files.  Movement  of  data  between  an  external  file  and 
an  internal  data  region  is  accomplished  by  a  GET  or  PUT  routine. 
Movement  of  data  between  internal  data  regions  is  accomplished  by  a 
TRANSFORMATION  routine.  Collectively,  these  routines  are  known  as 
Copy  Functions. 

The  current  implementation  of  the  BCM  is  represented  in  Figure  6, 
which  is  another  aspect  of  Figure  1.  Figure  6  should  be  interpreted 
somewhat  like  a  wiring  diagram.  The  direction  of  data  record  flow 
is  from  top  to  bottom,  and  each  line  is  marked  with  one  or  more  of 
the  three  possible  record  formats:  IL,  CT  (Clear  Text),  or  NT 
(Normalized  Text). 

Conceptually,  the  BCM  sports  a  variety  of  mode  switches  by  which  it 
can  be  parameterized.  Using  one  set  of  switches,  the  BCM  can  be 
caused  to  perform  one  of  at  least  three  basic  copy  types  (local 
copy,  remote  get,  or  remote  send).  Similar  switches  control 
conversion  of  data  among  the  dear-text,  normalized,  and  IL-encoded 
forms.  Switches,  marked  by  upper-case  names  in  figure  6,  direct 
flow  to,  from,  and  through  various  active  processing  components. 
Each  of  these  has  the  property  that  for  every  record  accepted,  an 
unpredictable  number  of  output  records,  including  zero,  may  be 
produced . 

These  notions  divide  the  switches  into  two  types: 
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Figure  6:  BOI  Parameterixation  Switches 
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3. 3. 1.1.  DATA  ROUTING  SWITCHES 

These  switches  are  concerned  with  getting  data  into  and  out  of  the 
BCM.  Their  settings  are  priauirily  determined  by  the  basic  t3rpe  of 
copy  ^>eration  being  executed,  and  by  the  types  of  the  external 
data  sets  to  be  processed.  These  switches  are: 

*  the  SOURCE_IS_LOCAL  switch 

*  the  KEEPIN6_A_SEC0NDART_C0PY  switch 

*  the  WRITING_AN_OUTPUT  switch 

*  the  00TPUT_IS_L0CAL  switch 

At  the  same  time  these  switches  are  set,  and  based  upon  the  same 
parametric  data,  each  data  region  is  assigned  a  set  of  "file  data 
attributes". 

3. 3. 1.2.  DATA  CONVERSION  SWITCHES 

These  switches  are  cmicemed  with  moving  data  .across  data  region 
boundaries.  Their  settings  are  primarily  determined  by  the 
relationships  between  the  file  data  attributes  assigned  the  two 
regions  inv loved.  These  switches  are: 

*  the  INPUT^FORMATTING^TyPE  switch 

*  the  OUrPUT_FORMATnNG_TyPE  switch 

Conceptually,  both  of  these  switches  can  be  set  to  perform  any 
type  of  data  conversion;  however,  in  the  present  implementation, 
most  potential  values  of  the  INPUT_FORHATnNG_TYPE  switch  are 
undefined.  This  results  in  the  restrictira  that  the  data  written 
through  the  secondary  output  file  must  be  an  untranslated, 
unrecoded  copy  of  the  input  stream. 

It  must  be  understood  that  the  switches  described  above  are 
abstractions  for  the  purpose  of  describing  the  logic  of  the 
machine.  In  fact,  the  functions  of  the  switches  are  implemented 
by  a  generator  mechanism  which  dynamically  binds  an  appropriate 
subroutine  into  the  machine  at  the  point  idiere  the  switch  has  its 
effect.  The  BCM  is  a  dynamically  bound  collection  of  routines, 
consisting  of  a  root  or  control  routine  and  five  slots  to  be 
filled  with  one  of  a  number  of  candidate  processing  modules  (see 
Figure  7).  FPCOPT,  the  control  routine  which  receives  control 
when  the  BCM  is  called,  is  responsible  for  the  selection  and 
control  of  the  other  modules.  From  the  values  set  in  the  three 
file  descriptors  (discussed  in  the  section  entitled  "CALLING  THE 
BCM") ,  FPCOPY  is  able  to  select  five  subroutines  appropriate  to 


Si^porting  th«  IBM  Fil*  Systea  in  NSW 
Nov«ab«r  20.  1980  —  Part  III:  BCM 

PAGE  42 


fill  in  the  five  variable  alota  for  the  particular  invocation  of 
the  BCM.  and  then  to  uae  theae  routinea  to  aet  up  a  copy 
operation,  to  perfora  the  copy,  and  to  clean  up  the  entire 
operation.  BCM  operation  ia  thua  coaqpoaed  of  four  phaaea: 

*  the  Generator  phaae 

*  the  Reaource  Allocation  phase 

*  the  Work  phase 

*  the  Resource  Freeing  phase 

More  will  be  said  about  these  phases  in  a  the  section  entitled 
PROCESSING  PHASES. 
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Figure  7:  The  Generated  Copy  Machine: 
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3.3.2.  DATA  STRUCTURES 


3.3.2. 1.  DATA  RECORDS 

There  are  three  forms  in  which  a  data  record  can  exist  for  the 
purposes  of  the  BCM. 

3.3.2. 1.1.  FORMATTED  CLEAR  TEXT 

Non-IL  records  are  stored  on  a  360  disk  in  a  format  called 
"formatted  clear  text",  or  simply  "clear  text".  Interpretation 
of  a  clear  text  record  generally  requires  a  full  knowledge  of 
the  Local  File  Attributes  (LFA's)  and  Physical  Storage 
Attributes  (PSA's)  for  its  tjqte;  therefore,  only  records  of  a 
SSO-native  type  can  exist  in  clear  text  form. 

A  clear  text  record  consists  of  a  single  string  of  bytes.  If 
the  RECFM  field  of  its  LFD  contains  the  letter  "A",  each  record 
will  begin  with  a  single  byte  of  ASA  carriage  control;  no  other 
type  of  format  effector  is  defined.  If  the  record  has  keys,  the 
key* length  field  of  the  GFD  and  the  key*offset  of  the  LFD 
together  define  a  substring  of  the  record  trhich  is  the  key;  the 
remaining  bytes  constitute  the  record  text  field. 

3.3.2. 1.2.  NORMALIZED  TEXT 

Normalized  Text  is  an  IL*like  internal  representation  for  a 
record  which  is  used  by  FP/360  when  converting  from  one  type  to 
another.  This  representation  consists  of  the  triple: 

(<skipcount>,  <key>,  <text>) 

where, 

*  <skipcount>  is  the  amount  of  vertical  movement  from  the 
preceding  line  to  the  current  one;  for  example,  zero  means 
that  the  current  line  is  to  overprint  the  preceding  line. 
There  is  also  a  reserved  value  of  <skipcount>  meaning  "form 
feed". 

*  <key>  is  the  isolated  key  string;  and 

*  <text>  is  a  string  containing  the  characters  or  bytes  of  the 
text  field  less  any  Insignificant  trailing  fill  bytes. 

A  record  in  this  representation  may  be  considered  to  be 
independent  of  any  of  the  local  host-specific  mappings  defined 
by  the  LFA's  and  PSA's. 
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IL  TRANSMISSION  BLOCKS 

An  IL  Transmission  Block  (reference  2)  is  the  form  in  which  data 
is  moved  between  Network  hosts  of  the  NSV  system.  The  block 
consists  of  a  string  of  transmission  bytes  of  a  specified  bit 
width  (but  the  BCM  will  process  only  8-bit  bytes  ).  This  string 
consists  of  a  two-byte  binary  count  field  followed  by  the 
indicated  number  of  data  bytes.  The  data  bytes  consist  of  a 
catenation  of  data  records,  each  cmitaining  an  encodement  of  the 
triple  (<sklpcount>,  <key>,  <text>).  The  encodement  is  such 
that  <skipcouat>  and  <key>  are  easily  extractable;  however, 
<text>  is  compressed  according  to  the  standard  NSW  data 
compression  grammar  (reference  2),  and  its  length  can  only  be 
determined  by  parsing  in  accord  with  that  grammar. 
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THE  DATA  REGION  DESCRIPTOR 

A  file  descriptor,  or  Data  Region  Descriptor,  has  a  dual 
personality,  as  can  be  se«i  from  Figure  2.  It  represents  the 
characteristics  of  an  actual  input  or  output  data  set  (local, 
remote,  or  null)  to  which  it  is  connected  through  one  of  the  GET 
or  PUT  Copy  Functions.  It  also  represents  a  set  of  internal  data 
characteristics  which,  together  with  another  file  descriptor  to 
which  this  one  is  connected  through  one  of  the  TRANSFORMATION  Copy 
Functions,  defines  a  set  of  data  conversions  for  that  Copy 
Function  to  implement. 

More  specifically,  the  Data  Region  Descriptor  contains  information 
of  the  following  sorts: 

*  Descriptors  of  the  current  record  residing  in  this  Data  Region. 

*  Descriptors  of  the  PL/ I  FII£  allocated  to  the  GET  or  PUT 
function  associated  with  this  Data  Region. 

*  Descriptors  of  the  Network  file  allocated  to  the  GET  or  PUT 
function  associated  with  this  Data  Region. 

*  The  "Global  Type"  name  associated  with  the  data  as  it  is 
represented  when  it  passes  through  this  region,  along  with  an 
expanded  descriptor  defining  Just  what  attributes  that  type  name 
implies . 

Because  of  the  great  variability  in  the  operations  that  may 
actually  go  on  in  moving  data  into  and  out  of  a  Data  Region,  the 
Data  Region  Descriptor  includes  many  data  elements  which  will  be 
used  only  in  specific  cases.  Still,  there  are  always  three  full 
descriptors  attached  to  a  BCN  execution,  regardless  of  the  paucity 
of  relevant  information  that  some  of  them  may  contain  in  some 
cases.  The  generator  phase  of  the  BCM  will  associate  with  a  Data 
Region  only  those  Copy  Function  routines  which  are  compatible  with 
the  information  actually  present  in  the  region. 

Note  that  the  Data  Region  Descriptor  does  not  include  any  actual 
data  record  buffers,  since  the  need  for  and  size  of  these  varies 
widely  according  to  the  selected  Copy  Function  routines. 
Accordingly,  buffers  are  managed  by,  and  belong  to,  the  Copy 
Function  subroutines  themselves. 
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3. 3. 2. 2.1.  FILE  AND  KECORD  CONTROL 


The  following  fields  of  the  Data  Region  Descriptor  (see  Figure 
2)  are  those  that  Copy  Functions  use  to  manipulate  PL/I  files 
and  data  buffers.  Except  as  noted,  this  means  that  the  BCM 
caller  need  not  concern  himself  with  them;  their  values  before, 
during,  and  after  execution  are  not  of  interest  to  him. 

*  TEXTAD  ■*-  points  to  the  data  string  which  represents  the 
current  data  record  associated  with  this  Data  Region 
Descriptor,  or,  in  the  case  of  normalized  internal  form,  to 
the  data  portion  of  the  record.  This  address  may  be  null  (or 
Invalid)  when  no  such  string  exists. 


*  KEYAD  --  the  address  of  the 
normalized  internal  data  record. 


extracted 


field 


*  LNGTEXT  —  is  the  length  of  the  current  data  string  (if  any) 
pointed  to  by  TEXTAD. 

*  LN6KEY  is  the  length  of  the  current  key  field  (if  any) 
pointed  to  by  KEYAD. 

*  SKIPS  is  an  accumulator  for  the  "skip  count”  cosiponent  of  a 
normalized  internal  data  record. 

*  FILENAME  ••  ddname  used  to  allocate  local  files.  Currently 
the  BCM  is  hard 'Wired  (in  FPCOPY)  to  always  use  INPUT,  NSVOUT, 
and  VSPOUT  for  the  three  possible  files. 

*  REALFILE  "  a  PL/1  FI1£  variable  which  is  set  to  one  of  the 
PL/I  FILE  constants  INFILE,  KPFILE,  or  OUTFILE.  This  is  true 
even  if  the  associated  file  is  a  network  file  instead  of  a 
local  data  set. 


yri'v. 


-  -li^i 


K 
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FILE  USAGE  DESCRIPTOR 

The  File  Usage  Descriptor  contains  data  pertinent  to  this 

particular  access  to  the  data: 

*  APPROX_BIT_COUNT  --  this  value  is  used  by  the  Resource 
Allocation  Routine  of  the  PUT  Copy  Function  to  allocate  space 
for  a  local  output  file.  It  is  determined  by  the  Resource 
Allocation  Routine  of  the  GET  Copy  Function.  If  the  input  is 
a  local  file,  it  is  calculated  from  the  number  of  track 
extents  allocated  to  the  file,  multiplied  by  the  number  of 
blocks  that  fit  on  that  track,  multiplied  by  the  number  of 
bits  in  a  block  of  the  file.  If  the  input  is  from  a  foreign 
host,  the  file  size  is  passed  as  part  of  the  Initial  NETWORK 
connection  to  the  Resource  Allocation  Routine,  and  the  value 
is  simply  stored. 

AT  present,  this  value  remains  constant  for  a  particular  copy 
operation,  even  through  IL  translation.  Once  it  is  determined 
for  the  input  data  region,  the  BCM  control  routine,  FPCOPY,  in 
a  breach  of  discipline,  copies  the  value  to  both  the  secondary 
and  primary  output  data  regions.  To  get  the  correct  value  for 
local  IL  data  sets,  it  should  be  multiplied  by  the  compression 
ratio  during  the  Resource  Allocation  Routines  of  the  translate 
Copy  Functions,  but  because  it  must  be  done  by  all  translate 
Resource  Allocation  Routines,  and  because  a  null  routine  is 
used  for  the  Resource  Allocation  Routine  in  some  cases,  FPCOPY 
performs  this  function  instead  of  a  special  routine  which 
would  do  nothing  else.  This  should  be  corrected  In  a  future 
version. 

*  ACTUAL_BLOCKSIZE  --  this  value  is  set  to  the  actual  blocks ize 
found  in  a  local  input  file,  or  chosen  for  a  local  output 
file. 

*  BUFFER_SIZE  --  the  BUFFER_SIZE  is  the  length  of  any  dynamic 
buffer  gotten  for  records  in  this  data  region.  It  is 
determined  and  set  by  the  Resource  Allocation  Routine  of  the 
particular  Copy  Function  that  outputs  into  this  region,  and 
used  by  the  Resource  Freeing  Routine  to  free  storage.  The 
value  for  local  files  is  assigned  from  the  LRECL  field  of  the 
PSD  (lRECL-4  for  files  of  RECFH>^).  For  data  files  at  foreign 
hosts,  the  BUFFER_SIZE  is  simply  the  agreed-upon  transmission 
size,  less  2  for  the  transmission  control  bytes. 

*  PASSWORD  --  that  data  needed  to  gain  access  to  the  file  on  the 
host.  The  BCM  currently  ignores  this  field  for  local  files. 
It  will  pass  this  value  to  foreign  hosts  for  a  NETWORK  input 
request . 
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DSNAHE  for  non-local  files,  this  field  is  ignored.  For 
local  files,  this  is  a  concatenation  of  PCD. DIRECTORY  and 
PCD.FNAME,  with  a  period  between  them,  and  with  any  "wild 
characters"  ("?")  replaced  by  whatever  alphanumerics  can  be 
found  to  result  in  a  unique  ID  for  a  local  data  set. 

USAGE  --  the  type  of  I/O.  Obviously,  only  certain  values  of 
this  datum  are  valid  for  certain  files.  At  the  present,  the 
BCM  only  looks  at  the  value  for  the  output  files.  The  values 
for  USAGE  are: 

*  0  ■*->  "Dummy":  the  file  represented  by  this  Data  Region 
Descriptor  is  not  to  be  read  or  written. 

*  1  -->  "Input":  this  Data  Region  Descriptor's  file 

exists  and  is  to  be  read. 

*  2  "NSW":  this  Data  Region  Descriptor's  file  will  be 
written,  and  is  to  be  created  in  the  NSW  File  Space. 

*  3  "Local":  this  Data  Region  Descriptor's  file  will 

be  written,  but  it  is  not  to  be  created  in  the  NSW  File 
Space.  , 


N  CM  CM  r4  CM  CM  CM 
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Figure  8:  The  Function  Control  Area 


PCP  POINTER 
AU^  RESOURCE  ROUTINE 
FREE  RESOURCE  ROUTINE 

work“routine  ” 

INPUT  REGION 
0UTPUT_REGI0N 
LOCAL  STATUS, 

3  HAS~LOCALLY  INITIALIZED 

3  has'locally" finalized 

3  HAS~BEEN  ALLOCATED 

3  hasItermInated 

2  GLOBAL  STATUS  POINTER 


POINTER, 

ENTRY, 

ENTRY, 

ENTRY, 

POINTER, 

POINTER, 

BIT(l)  ALIGNED, 
BIT(l)  ALIGNED, 
BIT(l)  ALIGNED, 
BIT(l)  ALIGNED, 
POINTER 


Figure  9:  The  Connection  Descriptor 


2  CONREQ,  /*  DIRECT-CONNECTIONS...  */ 
3  CTYPE  CHAR(4), 

3  CVIDTH  FIXED  BIN(IS), 

3  CID  FIXED  BIN(15), 

3  CQDEPTH  FIXED  BIN (IS), 

2  CONCONTROL, 

3  CONHANDLE  POINTER, 

3  CONCECB  FIXED  BIN(31), 

3  CONOECB  FIXED  BIN(31), 
i  3  CBPTR  POINTER, 

3  CBLENGTH  FIXED  BIN(15); 

I 

I 
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3. 3. 2. 3.  THE  FUNCTION  CONTROL  AREA 


The  function  control  area  is  illustrated  in  Figure  8.  It 

represents  one  of  the  Copy  Functions  that  move  data  into  and  out 
of  the  data  regions.  The  values  of  its  data  fields  are  determined 
by  FPCOPY  based  on  the  file  and  data  characteristics  of  the 
pertinent  Data  Region  Descriptors.  There  are  five  Function 

Control  Areas,  corresponding  to  the  five  Copy  Functions  (see 

figure  7).  Once  they  are  initialized,  FPCOPY  can  use  the  same 

calling  sequences  for  all  possible  BCH  conf iqurations ,  by  using 
the  values  of  appropriate  fields  of  the  Function  Control  Area. 
Those  fields  are: 

*  PCP_P0INTER  --  this  points  to  the  environment  descriptor  passed 
to  the  BCH  by  its  caller.  It  is  used  to  report  error  conditions 
and  is  also  used  by  the  Network  routines. 

*  ALL0C_RES0URCE_R0UTINE  The  address  of  the  selected  Resource 
Allocation  Routine. 

*  FREE_RES0URCE_R0UTINE  The  address  of  the  selected  Resource 
Freeing  Routine. 

*  V0RK_R0UTINE  **  The  address  of  the  selected  Work  Routine. 

*  INPUT_REGI0N  The  address  of  the  Data  Region  Descriptor  from 
which  this  Copy  Function  takes  its  input  records.  For  the  GET 
Copy  Function,  this  will  be  null. 

*  0UTPUT_REGI0N  The  address  of  the  Data  Region  Descriptor  to  which 
this  Copy  Function  gives  its  output  records.  For  the  PUT  Copy 
Functions,  this  will  be  null. 

*  L0CAL_STATUS  Status  flags  that  communicate  the  Control 

function's  status  between  calls  to  it  and  between  it  and  FPCOPY. 
The  bits  are: 

*  HAS_LOCALLY_INITIALIZED  --  any  Initializations  required  on 
the  first  entry  to  the  Work  Routine  have  been  completed. 

*  KAS_LOCALLY_FINALIZED  ••  the  Work  Routine  has  cleaned  up 
any  local  initializations  and  need  not  be  called  again. 

*  HAS_BEEN_ALLOCATED  ’■*  the  Resource  Allocation  Routine  for 
this  Copy  Function  has  successfully  completed. 


MoaiooiiMMiiiat 
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*  HAS_TERHINATED  —  the  output  data  of  this  Invocation  of 
the  Work  Routine  has  exhausted  the  input.  Implicit  in 
this  status  condition  is  a  request  for  more  input  on  the 
next  call.  FPCOPY  will  attempt  to  satisfy  this  by  calling 
the  previous  Copy  Function. 

*  GIX)BAL_STATUS_POINTER  --  the  address  of  global  status  flags 
referenced  by  all  Copy  Functions.  The  bits  pointed  to  are: 

*  CIiEAN_UP_NEEDED  --  local  Copy  Function  finalizations  must 
now  be  performed.  This  status  flag  is  set  only  on  the 
last  sequence  of  calls  to  the  Work  Routines.  This  flag  is 
set  after  any  error  or  end-of-data  condition  has  been 
found  and  processed. 

*  C0Py_E0D  --  the  GET  Copy  Function  has  exhausted  the  input 
data.  Preliminary  clean-up  can  be  performed. 

*  TRANSMISSION_ERROR  —  an  unrecoverable  error  has  occurred 
in  either  a  GET  or  PUT  Copy  Function.  The  BCM  is  to  be 
aborted . 

*  TRANSLATI0N_ERR0R  --  an  unrecoverable  erjror  has  occurred 
in  an  EDIT  Copy  Function.  The  BCM  is  to  be  aborted. 

*  ALL0CATI0N_ERR0R  --a  local  Copy  Function  initialization 
has  failed.  The  BCM  is  to  be  aborted. 
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3. 3. 2. 4.  THE  CONNECTION  DESCRIPTORS 

The  two  Connection  Descriptors  describe  the  two  possible  network 
connections  that  may  possibly  be  used  Instead  of  the  PL/I  FILEs 
described  in  the  Data  Region  Descriptors  for  the  INPUT  and  OUTPUT 
regions.  These  descriptors  logically  overlay  those  file 
descriptors.  They  are  not  in  the  same  control  block  only  for 
historical  reasons.  The  format  of  a  Connection  Descriptor  is 
shown  in  Figure  9.  We  do  not  describe  it  in  great  detail  here,  as 
it  is  only  of  interest  when  the  BCM  is  used  in  the  context  of  the 
NSW  File  Package,  and  in  that  context  it  is  self  explanatory. 

3. 3. 2. 5.  THE  ENVIRONMENT  DESCRIPTOR 


The  Environment  Descriptor  is  illustrated  in  Figure  3,  and 
described  in  the  section  entitled  "CALLING  THE  BCM". 

3. 3. 2. 6.  THE  DEFAULT  VALUES  TABLE 


't.vi  i' 


The  Default  Values  Table  is  illustrated  in  Figure  4,  and  described 
in  the  section  entitled  "CALLING  THE  BCM". 
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Figure  10:  Basic  Logic  After  Generation 


WORK  (i): 

I  IF  i  <  6 

I  THEN  I  UNTIL  F(i). HAS. TERMINATED 
I  I  i  CALL  F(i) .WORK  ROUTINE 

I  I  I  CALL  WORK  (i-fl) 


SETUP  (i): 

I  If  i  >  5 

I  THEN  I  CALL  WORK  (1) 

I 

I  ELSE  I  CALL  F(i).RESOURCE_ALLOC_ROUTINE 

I  I  IF  no  errors 

I  I  THEN  I  CALL  SETUP  (i-l-1) 

I  I  I  CALL  F(i) .RESOURCE_FREE_ROUTINE 


CALL  SETUP  (1) 
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3.3.3.  PROCESSING  PHASES 

BCM  operation  consists  of  four  phases:  The  Copy-Function  Generator 
phase,  the  Resource  Allocation  phase,  the  Work  phase,  and  the 
Resource  Freeing  phase.  Usually,  these  phases  are  executed  in  turn; 
however,  at  any  time,  in  any  subroutine  of  any  Selectable  Module,  an 
unrecoverable  error  may  occur.  If  this  happens,  FPCOPY  is  notified, 
an  error  message  is  generated,  and  FPCOPY  initiates  the  proper 
sequence  of  exiting  calls,  enabling  all  routines  to  accomplish  their 
needed  de-allocations,  before  control  is  returned  to  the  BCM  caller. 
The  actual  shape  of  the  logic  governing  execution  of  the  BCM  after 
generation  is  complete  is  Illustrated  in  Figure  10. 

3.3.3. 1.  THE  GENERATOR  PHASE 

The  five  Copy  Functions  are  represented  by  five  Function  Control 
Areas  (see  Figures  7,  9).  The  Generator  phase  consists  of 
assigning  Selectable  Modules  to  each  of  these  areas.  This  is  done 
by  examining  the  values  in  each  Data  Region  Descriptor  and 
selecting  routines  that  are  compatible  with  the  file  attributes 
and  required  transformations.  At  the  end  of  this  phase,  the 
Function  Control  Areas  have  been  initialized,  an4  the  machine  has 
the  appearance  shown  in  Figure  7. 

3. 3. 3. 2.  THE  RESOURCE  ALLOCATION  PHASE 

The  Resource  Allocation  phase  consists  of  executing  the  selected 
Resource  Allocation  routine  indicated  by  each  initialized  Function 
Control  Area.  These  routines  are  executed  in  a  well-defined 
order,  so  that  each  can  use  information  set  by  those  preceding. 

The  functions  of  the  Resource  Allocation  Routine  of  a  Copy 
Function  are  to  set  information  in  the  associated  data  regions, 
usually  copying  information  from  the  input  region  to  the  output 
region,  to  open  files,  and  to  allocate  dynamic  buffers  where  they 
are  indicsted.  The  Resource  Allocation  Routine  never  processes 
actual  file  data.  If  the  Resource  Allocation  Routine  completes 
normally,  its  work  will  be  undone  by  the  related  Resource  Free 
Routine.  If  it  completes  abnormally,  it  must  perform  its  own 
clean-up  and  indicate  its  failure.  In  such  a  case,  FPCOPY  will 
skip  directly  to  the  Resource  Freeing  phase,  beginning  at  the 
point  imomdlately  after  the  return  from  the  Resource  Freeing 
Routine  that  corresponds  the  the  Resource  Allocation  Routine  that 
failed. 


Supporting  the  IBM  File  System  in  NSW 
November  20,  1980  -*■  Part  III:  BCH 

PAGE  56 


3. 3. 3. 3.  THE  WORK  PHASE 


THe  Work  phase  copies  the  actual  data  records.  It  is  executed 
only  if  the  Resource  Allocation  Phase  completed  successfully.  It 
consists  of  an  iterated  and  structured  sequence  of  calls  to  the 
work  routines  of  the  Copy  Functions  in  sequence.  Each  function  is 
called  repeatedly  until  it  Indicates  that  it  requires  new  input; 
then  its  predecessor  is  called  to  supply  that  input.  Likewise, 
after  each  call  to  a  function,  if  that  call  has  produced  output, 
the  successor  function  is  called  to  dispose  of  that  output.  In 
this  way,  each  Copy  Function  can  emit  zero,  one,  or  more  output 
records  for  each  input  record  absorbed.  This  scheme  is  general 
enough  to  encompass  the  managmsent  of  routines  that  do  various 
kinds  of  blocking,  deblocking,  absorbing  of  null  records,  etc. 

When  a  Work  Routine  is  called,  the  input  string  pointed  to  by  the 
input  Data  Region  Descriptor  may  be  either: 

*  null  (an  Invalid  string  pointer) 

*  a  new  input  string 

*  the  residue  of  the  input  string  left  from  the  previous  call, 
and  when  it  exits,  the  input  string  is  left  as: 

*  null 

*  non-null,  l.e.  that  portion  of  the  original  input  string 
which  is  not  reflected  in  the  Work  Routine's  output  string. 
If  this  is  the  case,  the  HASJTERMINATED  flag  in  the  Copy 
Function's  local  status  area  will  not  be  set  and  the  Work 
Routine  will  be  called  again  by  FPCOPY  with  this  input. 

The  output  of  a  Work  Routine  on  exit  is  either: 

*  null 

*  non-null,  a  new  string.  There  is  no  concatenation  performed 
on  the  output  string  pointed  to  by  the  output  Data  Region 
Descriptor,  although  many  input  strings  may  be  condensed  and 
stored  in  a  buffer  internal  to  the  Work  Routine  itself.  The 
output  string  will  be  null  for  each  absorbed  input  until  a 
complete  output  string  is  finally  produced,  completely 
flushing  the  internal  buffer. 

The  actual  internal  mechanics  of  a  specific  Work  Routine, 
particularly  the  translation  operations,  are  highly  dependent  on 
the  given  attributes  of  the  input  and  output  Data  Region 
Descriptors . 
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When  a  Work  Routine  is  first  entered,  initializations  have  already 
been  perfomed  for  the  Copy  Function  by  the  Resource  Allocation 
Routine;  however,  soae  initializations  local  to  the  work  routine 
itself  isay  need  to  be  performed  on  the  first  entry.  It  is  up  to 
the  designer  of  a  Selectable  Module  to  determine  what 
initializations  are  massive  enough  to  warrant  inclusion  in  the 
separate  routine.  The  Work  Routine  perfonss  any  local 
initialization  and  sets  the  local  status  flag, 
HAS_L0CALLT__INITIAL1ZED.  It  is  then  able  to  continue  its  normal 
operations.  Note  that  during  the  final  call  to  a  Work  Routine, 
indicated  by  the  global  status  flag,  CIiEAN_UP_NEEDED,  the  Work 
Routine  must  undo  all  of  its  own  initializations. 

The  Work  Routine  may  encounter  an  end-of-data  or  error  condition 
during  its  own  internal  operations.  If  so,  it  sets  the 
appropriate  global  status  flag,  sets  its  output  string  to  null, 
and  exits.  When  a  Work  Routine  sets  such  a  global  flag,  FPCOPY 
will  take  appropriate  action.  Including  the  setting  of  the  global 
status  flag  CI£AN__UP_NEEDED.  FPCOPY  then  repeats  the  nested 
calling  of  WORK  routines  one  final  time.  Thus  each  Work  Routine 
needs  only  test  the  global  flag  CLEAN_UP_NEEDED  to  determine  if 
this  is  his  last  opportunity  to  perform  local  buffer  flushing  and 
finalization.  Again,  it  is  up  to  the  designer  of  a  Selectable 
Module  to  determine  which  finalizations  are  local  to  the  Work 
Routine  and  which  should  be  done  in  the  Resource  Freeing  Routine. 

THE  RESOURCE  FREEING  PHASE 

The  Resource  Freeing  phase  is  entered  after  the  Work  phase  is 
either  complete  or  bypassed.  It  consists  of  a  sequence  of  calls 
to  the  Resource  Freeing  routines  of  the  Copy  Functions. 

The  Resource  Free  Routine  of  a  Copy  Function  is  entered  only  if 
the  corresponding  Resource  Allocation  Routine  was  entered  and 
completed  successfully.  This  is  independent  of  whether  or  not  the 
Work  Routine(s)  were  ever  executed.  The  routine  frees  dynamic 
buffers,  closes  files,  etc.  Like  the  Resource  Allocation  Routine, 
the  Resource  Free  Routine  never  processes  file  data. 
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3.3.4.  SELECTABLE  MODULES 

A  Selectable  Module  is  the  entity  which  is  assigned  to  a  Copy 
Function.  The  five  Copy  Functions  are  (see  figure  7) : 

1)  Input, 

2)  Initial  transformation, 

3)  Secondary  output, 

4)  Final  transformation, 

5)  ■  Primary  output. 

Each  Selectable  Module  la  made  up  of  three  distinct  subroutines, 
corresponding  to  the  three  phases  of  the  copy  operation:  Resource 
Allocation,  Work,  and  Resource  Freeing.  These  entries  are  defined 
to  provide  flexibility  to  the  designer  of  a  Selectable  Module,  who 
may,  for  instance,  have  to  work  around  severe  maln*storage 
restrictions.  Logically,  though,  they  Implement  a  single  function, 
and  so  the  routines  that  comprise  them  must  be  treated  together. 

Every  subroutine  of  every  Selectable  Module  is  called  by  FPCOPY  with 
the  following: 


CALL  <funct ion> .  <phase-specif ic''entry*name> 
(ADOR  (<function-control>area>), 

ADOR  (<connectlon'Control'*block)); 


Because  of  the  uniformity  of  these  calls,  it  is  possible  to  support 
the  entire  range  of  BCM  subroutine  combinations  with  one  set  of 
calls  in  FPCOPY  (see  figure  10).  This  is  because  the  truly  variable 
parameters  to  the  routines  are  reflected  in  the  Copy  Function 
structure  and  in  the  Data  Region  Descriptors  already. 

3.3.4. 1.  TRANSFORMATIONAL  COMPONENTS 

Those  coiq)onents  of  the  Basic  Copy  Machine  which  are  responsible 
for  converting  the  format  or  content  of  file  data  will  now  be 
described.  In  general,  the  source  and  target  files  have 
attributes  which  may  be  the  same  or  different.  In  the  latter 
case,  the  component  Implements  conversion.  Input  records  are  not 
checked  for  conformity  to  dimensional  constraints,  but  output 
records  will  always  be  correct.  One  exception  must  be  noted:  If 
the  Global  File  Type  of  the  input  and  output  of  the  BCM  are  the 
saaM,  all  transformational  components  are  short-circuited,  and  no 
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attribute  policing  takes  place. 


3.3.4. 1.1.  NORMALIZER 


3.3.4. 1.2. 


3.3.4. 1.3. 


3.3.4. 1.4. 


3. 3. 4. 1.5. 


The  Normal izer  component  of  the  BCH  accepts  clear  text  records 
and  produces  norsialixed  text  records.  It  de- formats  its  input 
according  to  the  input>LFD  attributes.  Skip  counts  are 
generated  from  ASA  carriage  control,  if  present,  and/or 
completely  null  (text  and  key)  records,  or  null  records  with 
duplicate  keys. 

NORMALIZED  TEXT  EXPANDER 


The  Normalized  Text  Expander  component  accepts  normalized  text 
records  and  produces  clear  text  records .  The  output  is 
formatted  according  to  the  ouput-UD  attributes.  Skip  counts 
are  converted  to  ASA  carriage  control,  if  appropriate,  and/or  to 
records  with  blank  text  fields  and  possible  null  or  duplicate 
keys. 

IL  COMPRESSOR 

The  IL  Compressor  accepts  clear  text  records  and  produces 
compressed  IL  records.  Input  is  deformatted  according  to  the 
input *LFD  attributes.  Record  controls  are  generated  from  ASA 
carriage  control,  if  present,  and/or  completely  null  records,  or 
null  records  with  duplicate  keys. 

IL  EXPANDER 

The  IL  Expander  accepts  compressed  IL  records  and  produces  clear 
text  records.  Output  is  formatted  according  to  the  outpuf>LFD 
attributes.  Record  controls  are  converted  to  ASA  carriage 
control,  if  apprt^riate,  and/or  to  records  with  blank  text 
fields  and  possible  null  or  duplicate  keys. 

IL  REBLOCKER 

The  IL  Reblocker  will  accept  an  IL  transmission  block  and 
produce  one  or  more  IL  transmission  blocks  of  a  different 
maximum  transmission  block  size.  This  is  required,  for 
instance,  when  copying  an  IL-encoded  file  to  a  remote  file 
package  which  cannot  handle  the  blocksize  in  which  the  file 
already  exists. 

In  the  present  implementation,  the  IL  Reblocker  is  present  only 
as  a  stub.  This  means  that  situations  where  reblocking  might  be 
required  will  be  legal,  but  if  any  overlong  block  is  actually 
encountered,  it  will  be  treated  as  an  unrecoverable  copy  error. 
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Even  in  future  versions,  the  BCM  will  never  reblock  IL  to  obtain 
a  larger  block  size.  Since  reblocking  can  only  be  done  by 
completely  parsing  all  the  cosipressed  text,  it  is  assumed  that 
the  inefficiencies  of  handling  small  blocks  are  less  than  the 
effort  of  reblocking.  In  fact,  the  reblocker  will  use  the 
simplest  of  possible  algorithms: 

*  It  will  pass  blocks  that  are  already  short  enou^  straight 
through. 

*  If,  at  a  data  record  boundary  during  parsing  of  a  long  block, 
the  unparsed  residue  becomes  short  enough  to  be  legal  output, 
the  block  will  be  broken  at  that  point  regardless  of  how  short 
the  parsed  portion  may  be. 

*  Otherwise,  the  first  break  of  a  block  will  occur  at  the  last 
IL  record  boundary  before  the  one  which  would  make  the  first 
fragment  too  long. 

*  If  none  of  these  conditions  can  be  met,  (if  there  exists  a 
record  longer  than  the  IL  blocksize)  an  error  condition 
exists,  and  the  copy  machine  will  abort  the  entire  procedure. 

THE  NULL  THANSFORHATION 

Whenever  a  transformational  function  bridges  two  data  regions 
with  identical  characteristics,  so  that  no  data  editing  is 
indicated,  FPCOPY  selects  a  null  transformational  routine.  This 
routine  merely  copies  the  data  pointers  from  its  input  region  to 
its  output  region. 
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3. 3. 4. 2.  COPY  MACHINE  I/O  COMPONENTS 

The  Basic  Copy  Machine  has  one  input  and  two  output  streams. 
These  are  controlled  by  dynamically-selected  components.  In 
general,  these  components  are  not  sensitive  to  the  encodement  of 
the  records,  which  may  be  formatted  clear  text  or  IL  transmission 
blocks.  However,  the  present  implementation  will  not  support 
Network  transmission  of  clear  text  records,  so  the 
Network-handling  components  will  not  be  requested  to  process  other 
than  IL  transmission  blocks. 

3. 3. 4. 2.1.  THE  LOCAL  GET  FUNCTION 

The  local  get  function  is  switched  in  when  the  copy  machine's 
input  data  comes  from  a  local  data  set.  The  component's 
responsibilities  include: 

*  Locating  and  acquiring  control  over  the  input  data  set. 

*  Opening  the  data  set. 

^  Filling  in  any  PSA's  that  thus  become  known,  particularly  the 
total  fileaize. 


*  Acquiring  record  buffers. 


*  Retrieving  the  data 
end-of-file. 


set's  records  sequentially  until 


*  Releasing  buffers. 

*  Closing  and  releasing  the  data  set. 

*  Notifying  the  copy  machine  of  any  exceptional  conditions  that 
arise . 
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3. 3. 4. 2. 2.  THE  NETWORK  GET  FUNCTION 

The  Network  get  function  is  switched  in  when  the  copy  machine's 
input  data  comes  from  a  remote  file  package.  The  component's 
responsibilities  include: 


*  The  scheduling  and  completion  of  a  SENDME  procedure  call, 
directed  to  the  selected  remote  NSW  File  Package.  Most  of  the 
arguments  to  this  call  were  inputs  to  the  procedure  call  that 
the  BCM  is  Itself  executing.  Exceptions  are: 

1)  The  transmission  bytesixe  is  hardwired  at  8  bits. 


2)  The  maximum  transmission  record  size  is  taken  from  the 
Default  Values  Table. 

3)  The  "family  information"  parameter  will  be  of  PL/B8  type 
EMPTY  to  indicate  that  the  transmission  is  to  be  in  IL 
transmission  blocks. 

Note:  this  is  a  restriction  on  the  current 
implementation;  in  subsequent  versions,  clear  text  may 
be  transmitted  between  360  hosts. 

*  Recording  the  results  of  SENDME  for  later  use  by  other 
components.  Of  particular  interest  will  be  the  total  file 
size. 

*  Opening  a  PL/MSG  RECV  connection  (reference  3)  according  to 
the  negotiations  agreed  on  during  SENDME. 


*  Acquiring  record  buffers. 

*  Retrieving  the  file's  blocks  sequentially  until  either  the 
connection  closes  or  some  other  component  signals  that  an 
encoded  end-of-flle  has  been  found. 


*  Releasing  buffers. 

*  Closing  the  connection. 

*  Notifying  the  copy  machine  and  the  other  NSW  File  Package  of 
any  exceptional  conditions  that  arise. 
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3. 3. 4. 2. 3.  THE  LOCAL  PUT  FUNCTION 


^e  local  put  function  is  switched  in  when  any  of  the  copy 
machine's  output  goes  to  a  local  data  set.  This  is  usually  true 
during  the  "import",  "export",  and  "transport"  procedures.  If 
two  outputs  are  being  produced,  this  component  will  be  used 
twice,  but  with  different  parameters.  For  instance,  one  may  be 
writing  clear  text  and  the  other  IL  transmission  blocks.  In  any 
case,  the  cooiponent's  responsibilities  include: 


*  Creating  the  output  data  set,  and  acquiring  control  over  it. 
Notice  that  this  may  use  size  data  saved  by  the  selected  GET 
function.  If  the  data  set  name  is  fully  specified,  and  if  a 
data  set  of  that  name  already  exists,  then  the  old  copy  will 
be  deleted. 


*  Opening  the  data  set. 


*  Writing  records  sequentially  until  signaled  by  the  copy 
machine  that  no  more  reoiain. 


*  Closing  and  releasing  the  data  set,  or  deleting  it  if  there 
was  an  error. 


*  Notifying  the  copy  machine  of  any  exceptional  conditions  that 

arise. 


3. 3. 4. 2. 4.  THE  NULL  PUT  FUNCTION 


When  one  of  the  BCH's  output  streams  is  not  to  be  produced, 
FPCOPY  selects  a  null  PUT  routine.  This  routine  does 
essentially  nothing  at  all. 
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3.3.4. 2.5.  THE  NETWORK  PUT  FUNCTION 


The  Network  put  function  Is  switched  In  when  the  copy  machine's 
primary  output  data  goes  to  a  remote  host.  This  Is  the  case 
when  the  BCM  Is  executing  an  NSW  SENDME  procedure  call.  The 
cooqwnent's  responsibilities  Include: 

*  Replying  to  the  SEND  procedure  being  executed.  The  following 

data  Is  returned: 

1)  The  connection  Identifier  Is  hardwired  as  1. 

2)  The  transmission  byteslze  Is  hardwired  at  8  bits. 

3)  The  actual  IL  transmission  block  size  is  the  minimum  of: 
a)  the  size  requested  in  the  call;  and  b)  a  limiting 
value  taken  from  the  Default  Values  Table. 

4)  The  "family  Information"  parameter  will  be  of  NSWB8  t3^e 
EMPTY  to  Indicate  that  the  transmission  Is  to  be  In  IL 
transmission  blocks. 
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Note;  This  Is  a  restriction  ^In  the  current 
Implementation:  In  subsequent  versions,  clear  text 
transmission  may  be  supported  between  360  family  hosts. 

*  Opening  a  PL/MSG  SEND  connection  according  to  the  negotiations 
agreed  on. 

*  Transmitting  the  file's  blocks  sequentially  until  signaled  by 
the  copy  machine  that  no  more  remain. 

*  Transmitting  an  in-band  ending  status  mark  to  the  remote  File 
Package. 

*  Closing  the  connection. 
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*  Notifying  the  copy  machine  of  any  exceptional  conditions  that 
arise. 
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3.4.  APPENDIX  --  AVAILABLE  GFT'S 


GFT=360 -KEYPUNCH, 

★ 

RECFM=FB , 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECL=80 , 

(80,  121,  137,  ETC.) 

★ 

BLKSIZE=(400,6400), 

((MIN,  MAX)  OR  FIXED) 

* 

CMPFAC=40, 

(EST  IL/DISK  BYTES  *  100) 

* 

KOFFS=73, 

(1-ORG,  IN  TEXT  FIELD  ONLY) 

* 

F0LDMGN=1 , 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

DIM=2, 

(NATIVE  DIMENSION) 

* 

UC=Y, 

FORCE  UC:  (YES,  NO) 

ie 

KEYHDL=B, 

(REQ,  GEN,  BLANK,  NO) 

* 

L0NGR=F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

* 

SH0RTR=P, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

■k 

L0NGP=A, 

(TRUNC,  FOLD,  ALLOW;  L  PAGES) 

k 

SH0RTP=D, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

k 

IN0NLY=N, 

(YES,  NO) 

k 

CLASS=T, 

(TEXT,  BINARY) 

k 

LNGKEY=8 , 

(NOT  IN  THE  DA  SENSE) 

k 

TXTLNG=72, 

TEXT  LENGTH  RANGE 

k 

DIM1=F0RBID, 

DIMENSIONAL  PREFERENCES 

k 

DIM2=PERMIT, 

k 

DIM3=(ASK,1), 

DIM4=(ASK,2) 

k 

GFT=360-PRINT, 

* 

RECFM=VBA, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECL=137, 

(80,  121,  137,  ETC.) 

* 

BLKSIZE=(141,4000), 

((MIN,  MAX)  OR  FIXED) 

* 

SPACE=(010,02), 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAC=50 , 

(EST  IL/DISK  BYTES  *  100) 

k 

KOFFS=0 , 

(1-ORG,  IN  TEXT  FIELD  ONLY) 

k 

FOLDMGN=l, 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

k 

DIM=3, 

(NATIVE  DIMENSION) 

k 

UC=N, 

FORCE  UC:  (YES,  NO) 

k 

KEYHDL=N, 

(REQ,  GEN,  BLANK,  NO) 

k 

LONGR=F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

k 

SHORTR=P, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

k 

LONGP=F, 

(TRUNC,  FOLD,  ALLOW;  L  PAGES) 

k 

SHORTP=D, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

k 

INONLY=N, 

(YES,  NO) 

k 

CLASS=T, 

(TEXT,  BINARY) 

k 

LNGKEY=0, 

(NOT  IN  THE  DA  SENSE) 

k 

TXTLNG=( 1,132), 

TEXT  LENGTH  RANGE 

k 

DIM1=F0RBID, 

DIMENSIONAL  PREFERENCES 

k 

DIM2=( PERMIT, 2), 

k 

DIM3=(PERMIT,1), 

DIM4=(ASK,3) 

k 
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6FT^360-BINARY. 

* 

RECFM^VBS, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECL^O, 

(80,  121,  137,  ETC.) 

* 

BLKSIZEs( 1.4000), 

((MIN,  MAX)  OR  FIXED) 

* 

SPACE=(005,01), 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAC=60, 

(EST  IL/DISK  BYTES  *  100) 

* 

KOFFS*0, 

(1-ORG,  IN  TEXT  FIELD  ONLY) 

* 

FOLDMGN=l, 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

DIM=2, 

(NATIVE  DIMENSION) 

* 

UC=N. 

FORCE  UC:  (YES,  NO) 

* 

KEYHDL=N, 

(REQ,  GEN,  BLANK,  NO) 

* 

L0NGR=F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

INONLY*N, 

(YES,  NO) 

* 

CLASSsB, 

(TEXT,  BINARY) 

* 

KPFILL=Y, 

(TRAIL  FILLS  ARE  SIGNIF;  Y, 

N)  * 

SUPRXL=Y, 

(PERFORM  CODE  TRANS;  Y,  N) 

* 

LNGKEY>0, 

(NOT  IN  THE  DA  SENSE) 

■k 

DIM1»F0RBID, 

DIMENSIONAL  PREFERENCES 

* 

DIM2*PERMIT, 

* 

DIM3>F0RBID, 

* 

DIH4»F0RBID 

GFT-360-L0AD, 

* 

RECFM-U, 

(FB,  VBA,  ETC.  ETC.) 

k 

LRECL-0, 

(80,  121,  137,  ETC.) 

k 

BLKSIZE=( 1,20000), 

((MIN,  MAX)  OR  FIXED) 

k 

SPACE=(010,10,20), 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CNPFAC»100, 

(EST  IL/DISK  BYTES  *  100) 

k 

K0FFS*0, 

(1-ORG,  IN  TEXT  FIELD  ONLY) 

k 

F0LDMGN>0, 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

k 

DIMa2, 

(NATIVE  DIMENSION) 

k 

UC-N, 

FORCE  UC:  (YES,  NO) 

* 

KEYHDLaN, 

(REQ,  GEN,  BLANK,  NO) 

* 

LONGR-F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

k 

INONLYaN, 

(YES,  NO) 

* 

CLASSaB, 

(TEXT,  BINARY) 

* 

KPFILL=Y, 

(TRAIL  FILLS  ARE  SIGNIF;  Y, 

N)  * 

SUPRXLaY, 

(PERFORM  CODE  TRANS;  Y,  N) 

k 

LNGKEYaO, 

(NOT  IN  THE  DA  SENSE) 

k 

DIHlaFORBID, 

DIMENSIONAL  PREFERENCES 

* 

DIM2aPERMIT, 

k 

DIM3»FORBID, 

k 

DIM4aF0RBID 
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GFT=360-PLI -CARDS, 

* 

RECFM=FB, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECI.S80, 

(80,  121,  137,  ETC.) 

* 

BLKSIZEs(80,4000), 

((MIN,  MAX)  OR  FIXED) 

* 

SPACE»(005,01), 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAC«40, 

(EST  IL/DISK  BYTES  *  100) 

* 

KOFFS»73, 

(1-ORG,  IN  TEXT  FIELD  ONLY) 

■k 

F0LDMGa4»l, 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

DItfsZ, 

(NATIVE  DIMENSION) 

* 

UC=Y, 

FORCE  UC:  (YES,  NO) 

* 

KEYHDI^B. 

(REQ,  GEN,  BLANK,  NO) 

* 

L0NGR»F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

* 

SH0RTR«P, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

LONGPsA, 

(TRUNC,  FOLD,  ALLOW;  L  PAGES) 

* 

SH0RTP=D, 

(PAD,  DON’T  PAD;  SHORT  RECS) 

* 

INONLYsN, 

(YES,  NO) 

* 

CLASSY, 

(TEXT,  BINARY) 

* 

LNGKEY>8, 

(NOT  IN  THE  DA  SENSE) 

* 

TmNG»72, 

TEXT  LENGTH  RANGE 

* 

DIM1»F0RBID, 

DIMENSIONAL  PREFERENCES 

* 

DIM2»PERMIT, 

* 

DIM3>(ASK,1), 

DIM4»(ASK,2) 

* 

Grr»360 -PLI -CC -CARDS , 

* 

RECFH»FB, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECL-80, 

(80,  121,  137,  ETC.) 

* 

BLKSIZE«(80,4000), 

((MIN,  MAX)  OR  FIXED) 

* 

SPACEs(005,01), 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAC-40, 

(EST  IL/DISK  BYTES  *  100) 

* 

KOFFS-73, 

(1-ORG,  IN  TEXT  FIELD  ONLY) 

* 

F0LDMGN«2, 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

DIM>2, 

(NATIVE  DIMENSION) 

* 

UC-Y, 

FORCE  UC:  (YES,  NO) 

* 

KEYHDL*>B, 

(REQ,  GEN,  BLANK,  NO) 

* 

LONGRsF, 

(TRUNCATE,  FOLD;  LONG  RECS) 
(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

SHORTR«P, 

* 

LONGP-A, 

(TRUNC,  FOLD,  ALLOW;  L  PAGES) 

* 

SHORTPbD, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

INONLY-N, 

(YES,  NO) 

* 

CLASSY, 

(TEXT,  BINARY) 

* 

LNGKEY-8, 

(NOT  IN  THE  DA  SENSE) 

* 

TmNG»72, 

TEXT  LENGTH  RANGE 

* 

DIM1>F0RBID, 

DIMENSIONAL  PREFERENCES 

* 

DIM2-PERHIT, 

* 

DIM3»(ASK,1), 

DIN4«(ASK,2) 

•k 

1 

( 

\ 
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6FTb360-PLI -source , 

* 

RECFMi^, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECL-104. 

(80,  121,  137,  ETC.) 

* 

BLKSIZE«(104,4000). 

(CHIN,  MAX)  OR  FIXED) 

* 

SPACE«(005,01), 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAC>50, 

(EST  IL/DISK  BYTES  *  100) 

* 

KOFFS^l, 

(l-ORG,  IN  TEXT  FIEIJ)  ONLY) 

* 

FOLDHGN-1, 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

DIH»2, 

(NATIVE  DIMENSION) 

* 

UC»Y, 

FORCE  UC:  (YES,  NO) 

* 

KEYHDLsB, 

(REQ,  GEN,  BLANK,  NO) 

* 

L0NGR»F. 

(TRUI«:ATE,  FOLD;  LONG  RECS) 

* 

SHORTRsP, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

L0NGP»A, 

(TRUNC,  FOLD,  ALLOW;  L  PAGES) 

* 

SH0RTP=D, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

IN0NLY»N, 

(YES,  NO) 

* 

CLASSY, 

(TEXT,  BINARY) 

* 

LNGKEY-8, 

(NOT  IN  THE  DA  SENSE) 

* 

TXTLNG=(1,92), 

TEXT  LENGTH  RANGE 

* 

DIMl-FORBID, 

DIMENSIONAL  PREFERENCES 

* 

DIH2>PERMIT, 

* 

DIM3«(ASK,1). 

DIM4a(ASK,2) 

* 

GFT^360-PLI-CC-S0URCE , 

* 

RECFH*VB, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECLF104, 

(80.  121,  137,  ETC.) 

* 

BLKSIZE>(104,4000), 

((MIN,  MAX)  OR  FIXED) 

* 

SPACE-(005,01), 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAC«50, 

(EST  IL/DISK  BYTES  *  100) 

* 

KOFFS-1, 

(l-ORG,  IN  TEXT  FIELD  ONLY) 

* 

FOLDNGN-2, 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

e 

DIN-2, 

(NATIVE  DIMENSION) 

* 

UC-Y, 

FORCE  UC:  (YES,  NO) 

* 

KEYHDLfB, 

(REQ,  GEN,  BLANK,  NO) 

* 

LONGR-F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

* 

SHORTR-P, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

L0N6P-A, 

(TRUNC,  FOLD.  ALLOW;  L  PAGES) 

* 

SHORTP-D, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

INONLY-N, 

(YES,  NO) 

* 

CLASSY, 

(TEXT,  BINARY) 

* 

LNGKEY-8, 

(NOT  IN  THE  DA  SENSE) 

* 

TXrLNG>(l,92), 

TEXT  LENGTH  RANGE 

* 

DIMl-FORBID, 

DIMENSIONAL  PREFERENCES 

* 

DIH2-PERHIT, 

* 

DIM3«(ASK,1), 

DIM4-(ASK,2) 

* 

1 
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GFT>360-FORTRAN-SOURCE , 

* 

RECFI^FB, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECL^SO, 

(80,  121,  137,  ETC.) 

* 

BLKSIZE>(80,4000), 

((MIN,  MAX)  OR  FIXED) 

* 

SPACE-(005,01), 

(PRIMARY,  SEC(WDARY,  DIRECTORY)* 

CMPFAO40, 

(EST  IL/DISK  BYTES  *  100) 

* 

KOFFS-73, 

(1-ORG,  IN  TEXT  FIELD  ONLY) 

* 

FOLDMGN>7, 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

DIM«2, 

(NATIVE  DIMENSION) 

* 

UC»Y, 

FORCE  UC:  (YES,  NO) 

* 

KEYHDL-B, 

(REQ,  GEN,  BLANK,  NO) 

* 

L0NGR»F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

* 

SHORTR-P, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

LONGP-A, 

(TRUNC,  FOLD,  ALLOW;  L  PAGES) 

* 

SHORTP^D, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

INONLY«N. 

(YES,  NO) 

* 

CLASSY, 

(TEXT,  BINARY) 

* 

LNGKEY>8, 

(NOT  IN  THE  DA  SENSE) 

* 

TXTLNG-72, 

TEXT  LENGTH  RANGE 

* 

OIMl«FORBID, 

DIMENSI(»tAL  PREFERENCES 

* 

DIM2«PERMIT. 

* 

DIM3»(ASK,1), 

* 

DIH4>(ASK,2) 

e 

GFT-360-LIST, 

* 

RECFM-VB, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECI^136, 

(80,  121,  137,  ETC.) 

* 

BIXSIZE-(140,4000), 

((MIN,  MAX)  OR  FIXED) 

* 

SPACE-(010,02), 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAC«50. 

(EST  IL/DISK  BYTES  *  100) 

It 

KOFFS^, 

(1-ORG,  IN  TEXT  FIELD  ONLY) 

* 

FOLDMGN-l, 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

DIM-2, 

(NATIVE  DIMENSION) 

* 

UC-N, 

FORCE  UC:  (YES,  NO) 

* 

KEYHDLpN, 

(REQ,  GEN,  BLANK,  NO) 

* 

LONGR-F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

* 

SHORTR-P, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

L0N6P-F, 

(TRUNC,  FOLD,  ALLOW;  L  PAGES) 

* 

8HORTP-D, 

(PAD,  DCm'T  PAD;  SHORT  RECS) 

* 

INONLY-N, 

(YES,  NO) 

* 

CLASSY, 

(TEXT,  BINARY) 

* 

LN6KEY-0, 

(NOT  IN  THE  DA  SENSE) 

* 

TXnK6-(  1,132), 

TEXT  LENGTH  RANGE 

* 

DIMl-FORBID, 

DIMENSIONAL  PREFERENCES 

* 

DIM2-(PERMIT,1), 

* 

DIM3«(PERMIT,2), 

DIM4-(ASK,3) 

* 
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GFT-360-CAROS, 

* 

RECFM-FB, 

(FB,  VBA,  ETC.  ETC.) 

* 

LSECL>80, 

(80,  121,  137,  ETC.) 

* 

BLICSIZE»(80,4000) , 

((MIN,  MAX)  OR  FIXED) 

* 

SPACEs(20.40), 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFACS40. 

(EST  IL/DISK  BYTES  *  100) 

* 

F0LDHGN»1. 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

DItts2. 

(NATIVE  DIMENSION) 

* 

UC^, 

FORCE  UC:  (YES,  NO) 

* 

L0NGR»F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

* 

SHORTRsP, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

LONGP-A, 

(TRUNC,  FOLD,  ALLOtf;  L  PAGES) 

* 

SH0RTP=D, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

INONLYaN, 

(YES,  NO) 

* 

CLASS-T, 

(TEXT,  BINARY) 

* 

T3CnJNG-80, 

TEXT  LENGTH  RANGE 

* 

DIMlsFORBIO, 

DIMENSIONAL  PREFERENCES 

* 

DIH2aPERMIT, 

* 

DIM3«(ASK,1). 

DIH4«(ASK,2) 

* 

GFT-360-OBJECT, 

* 

RECFM-FB, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECL^O, 

(80,  121,  137,  ETC.) 

* 

BLKSIZE>(80,3200), 

((MIN,  MAX)  OR  FIXED) 

* 

SPACE«(20,40), 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CNPFAC-40, 

(EST  IL/DISK  BYTES  *  100) 

* 

K0FFS>73, 

(1-ORG,  IN  TEXT  FIELD  ONLY) 

* 

FOLDHGNol, 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

DIM>2, 

(NATIVE  DIMENSION) 

* 

UC^, 

FORCE  UC:  (YES,  NO) 

* 

KEYHDL-G, 

(REQ,  GEN,  BLANK,  NO) 

* 

L(»<GR>F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

* 

SHORTR-P, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

LONGP-A, 

(TRUNC,  FOLD,  ALLOW;  L  PAGES) 

* 

SHORTP-D, 

(FAD,  DON'T  PAD;  SHORT  RECS) 

* 

INONLY-N, 

(YES,  NO) 

* 

CLASS-B, 

(TEXT,  BINARY) 

* 

KPFILI^Y, 

(TRAIL  FILLS  ARE  SIGNIF;  Y,  N) 

* 

SUPRXL-Y, 

(PERFORM  CODE  TRANS;  Y,  N) 

* 

LN6KEY-8, 

(NOT  IN  THE  DA  SENSE) 

* 

TmN6>72, 

TEXT  LENGTH  RANGE 

* 

DIMl-FORBID, 

DIMENSIONAL  PREFERENCES 

* 

DIM2«PERMIT, 

* 

DIM3*(ASK,1), 

DIM4«(ASK,2) 

* 
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6FT^360-OVERPRINT.  * 

RECTM-VBA,  (FB,  VBA,  ETC.  ETC.)  * 

UIECI^137,  (80,  121,  137,  ETC.)  * 

BLKSIZE-( 141, 4000),  ((MIN,  MAX)  OR  FIXED)  * 

SPACE«(010,02),  (PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAOSO,  (EST  IL/DISK  BYTES  *  100)  * 

KOFFS^,  (1-ORG,  IN  TEXT  FIELD  ONLY)  * 

F0LDM6N-1,  (1  0R6,  IN  TEXT  FIELD  ONLY)  * 

DIM-4,  (NATIVE  DIMENSION)  * 

UC-N,  FORCE  DC:  (YES,  NO)  * 

KEYHDMf,  (REQ,  6EN,  BLANK,  NO)  * 

LCmOR-F,  (TRUNCATE,  FOLD;  LONG  RECS)  * 

SHORTR-P,  (PAD,  DON'T  PAD;  SHORT  RECS)  * 

LONGP-F,  (TRUNC,  FOLD,  ALLOW;  L  PAGES)  * 

SHORTP-D,  (PAD,  DON'T  PAD;  SHORT  RECS)  * 

INONLY-N,  (YES,  NO)  * 

CLASSY,  (TEXT,  BINARY)  * 

LNGREY-0,  (NOT  IN  THE  DA  SENSE)  * 

TXTU(G-( 1,132),  TEXT  LENGTH  RANGE  * 

DIMl-FORBID,  DIMENSIONAL  PREFERENCES  * 

DIM2-(PERMIT,3),  * 

DIN3-(PERMIT,2),  * 

DIN4-(PERMIT,1) 

GFT-360-ASM-SOURCE,  * 

RECFM-FB,  (FB,  VBA,  ETC.  ETC.)  * 

LRECL-80,  (80,  121,  137,  ETC.)  * 

BLRSIZE«(80,4000),  ((MIN,  MAX)  OR  FIXED)  * 

SPACE«(005,01),  (PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAC-40,  (EST  IL/DISK  BYTES  *  100)  * 

KOFFS-73,  (1-ORG,  IN  TEXT  FIELD  ONLY)  * 

FOLDMGN-16,  (1  ORG,  IN  TEXT  FIELD  ONLY)  * 

DIM-2,  (NATIVE  DIMENSION)  * 

UC-Y,  FORCE  UC:  (YES,  NO)  * 

KEYHDL-G,  (REQ,  GEN,  BLANK,  NO)  * 

LONGR-F,  (TRUNCATE,  FOLD;  LONG  RECS)  * 

SHORTR-P,  (PAD,  DON'T  PAD;  SHORT  RECS)  * 

LONGP-A,  (TRUNC,  FOLD,  ALLOW;  L  PAGES)  * 

SHORTP-D,  (PAD,  DON'T  PAD;  SHORT  RECS)  * 

INONLY-N,  (YES,  NO)  * 

CLASSY,  (TEXT,  BINARY)  * 

LNGKEY-8,  (NOT  IN  THE  DA  SENSE)  * 

TmNG-72,  TEXT  LENGTH  RANGE  * 

DIMl-FORBID,  DIMENSIONAL  PREFERENCES  * 

DIM2-PESMIT,  * 

DIM3-(ASK,1),  * 

DIM4-(ASK,2) 


Supporting  the  IBM  File  System  in  NSW 
November  20,  1980  *■>  Part  III:  BCH 

PAGE  72 


6FT-360-COBOL-SOURCE , 

* 

RECFM-FB, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECI^O, 

(80,  121,  137,  ETC.) 

* 

BU[SIZE>(80.4000). 

((MIN,  MAX)  OR  FIXED) 

* 

SPACE-(005,01), 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAO40, 

(EST  IL/DISK  BYTES  *  100) 

* 

KOFFSal, 

(1-ORG,  IN  TEXT  FIELD  ONLY) 

* 

FOLDHGN-6. 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

DIH-2, 

(NATIVE  DIMENSION) 

* 

UC-Y, 

FORCE  OC:  (YES,  NO) 

* 

KEYHDI^, 

(REQ,  GEN,  BLANK,  NO) 

* 

LONGR-F. 

(TRUNCATE,  FOLD;  LONG  RECS) 

* 

SHORTl^P, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

LONOP-A, 

(TRUNC,  FOLD,  ALLOW;  L  PAGES) 

* 

SHORTP-O, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

IN(mLY>44, 

(YES,  NO) 

* 

CLASSY. 

(TEXT,  BINARY) 

* 

LNGKEY>6, 

(NOT  IN  THE  DA  SENSE) 

* 

TXrLNG-74, 

TEXT  LENGTH  RANGE 

* 

OIHl-FORBID, 

DIMENSIONAL  PREFERENCES 

* 

DIH2-PERMIT, 

* 

DIM3-(ASK,1), 

* 

DIM4«(ASK,2) 

GFT^360 >COBOL-SEQ-SOURCE , 

* 

RECFHbFB, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECL-80, 

(80,  121,  137,  ETC.) 

* 

BLKSIZE«(80,4000), 

((MIN,  MAX)  OR  FIXED) 

* 

SPACE«(00S,01), 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAC>40, 

(EST  IL/DISK  BYTES  *  100) 

* 

KOFFS-73, 

(1-ORG,  IN  TEXT  FIELD  ONLY) 

* 

F0LDM(9)«12, 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

DIH-2, 

(NATIVE  DIMENSION) 

* 

UC«Y, 

FORCE  UC:  (YES,  NO) 

* 

KEYHDL-G, 

(REQ,  GEN,  BLANK,  NO) 

* 

LONGR-F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

* 

SHORTR-P, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

L0N6P-A, 

(TRUNC,  FOLD,  ALLOW;  L  PAGES) 

* 

SH0RTP»0, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

•k 

INONLY«N, 

(YES,  NO) 

* 

CLASS-T, 

(TEXT,  BINARY) 

* 

LNGKEY-8, 

(NOT  IN  THE  DA  SENSE) 

* 

TmN6-72, 

TEXT  LENGTH  RANGE 

* 

DIMl-FORBID, 

DIMENSIONAL  PREFERENCES 

* 

DIH2-PERMIT, 

* 

DIM3-(ASK,1), 

DIM4«(ASK,2) 

* 
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GFT^360-0RIGINAL.  * 

RECFM-VBA,  (FB,  VBA,  ETC.  ETC.)  * 

LRECL-1000,  (80,  121,  137,  ETC.)  * 

BLKSIZE«( 1004, 4000),  ((MIN,  MAX)  OR  FIXED)  * 

SPACE>(010,02),  (PRIMARY,  SECCMDARY,  DIRECTORY)* 

CMPFAC-100,  (EST  IL/DISK  BYTES  *  100)  * 

KOFFS-O,  (1-ORG,  IN  TEXT  FIELD  ONLY)  * 

FOLDHSi-l,  (1  ORG,  IN  TEXT  FIELD  ONLY)  * 

DIM-4,  (NATIVE  DIMENSION)  * 

UC^,  FORCE  UC:  (YES,  NO)  * 

KEYHDMt,  (REQ.  GEN.  BLANK.  NO)  * 

L(mGR-F,  (TRUNCATE.  FOLD;  LONG  RECS)  * 

SHORTR-P,  (PAD,  DON'T  PAD;  SHORT  RECS)  * 

LONGP-F.  (TRUNC,  FOLD.  ALLOW;  L  PAGES)  * 

SHORTP-D,  (PAD,  Dm'T  PAD;  SHORT  RECS)  * 

I)K»a.Y-T,  (YES,  NO)  * 

CLASS-T,  (TEXT.  BINARY)  * 

LN6KEY-0,  (NOT  IN  THE  DA  SENSE)  * 

TmNG-(  1,1000),  TEXT  LENGTH  RANGE  * 

0IH1^>ERMIT.  DIMENSIONAL  PREFERENCES  * 

DIM2-PEBMIT.  * 

DIN3-PERMIT.  * 

DIM4-PESMIT 

GFT-360'ORIGINAL-BIN.  ****** 

RECFM-VBA,  (FB,  VBA,  ETC.  ETC.)  ♦ 

LRECL-1000,  (80,  121,  137,  ETC.)  * 

BLKSIZE-( 1004, 4000),  ((MIN,  MAX)  OR  FIXED)  * 

SPACE-(010,02),  (PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAC-lOO,  (EST  IL/DISK  BYTES  *  100)  * 

KOFFS-0,  (1-ORG,  IN  TEXT  FIELD  ONLY)  * 

FOLDM(»i-l,  (1  ORG,  IN  TEXT  FIELD  WILY)  * 

DIM-4,  (NATIVE  DIMENSION)  * 

UC-N,  FORCE  UC:  (YES,  NO)  * 

KEYHDL-N,  (REQ,  GEN,  BLANK.  NO)  * 

L0N6R*F.  (TRUNCATE,  FOLD;  LONG  RECS)  * 

SHORTR-P.  (PAD,  DON'T  PAD;  SHORT  RECS)  * 

LONGP-F,  (TRUNC,  FOLD,  ALLOW;  L  PAGES)  * 

SHORTP-D.  (PAD,  DON'T  PAD;  SHORT  RECS)  * 

INONLY-Y,  (YES,  NO)  * 

CLA88-B,  (TEXT,  BINARY)  * 

LN6KEY-0,  (NOT  IN  THE  DA  SENSE)  * 

TXTLNO-( 1,1000),  TEXT  LENGTH  RANGE  * 

DIMl-PERMIT,  DIHENSI(»fAL  PREFERENCES  * 

DIH2-PERHIT,  * 

DIH3-PERHIT.  * 

DIH4-PERHIT 
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6FT^360-ASM80-S0URCE . 

* 

RECFH-FB, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECIi^O. 

(80,  121,  137,  ETC.) 

* 

BLKSIZE«(80.4000) . 

((MIN,  MAX)  OR  FIXED) 

* 

SPACE«(005.01). 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAO40. 

(EST  IL/DISK  BYTES  *  100) 

* 

K0FFS»73, 

(1-ORG,  IN  TEXT  FIELD  ONLY) 

* 

FOLDHGN-16, 

(1  ORG,  IN  TEXT  FIELD  (M.Y) 

* 

DIH^, 

(NATIVE  DIMENSION) 

* 

UOY, 

FORCE  UC:  (YES.  NO) 

* 

KEYHDL-6, 

(REQ,  GEN,  BLANK,  NO) 

* 

LONGR-F. 

(TRUNCATE.  FOLD;  LONG  RECS) 

* 

SH0RTR«P, 

(PAD,  D(»('T  PAD;  SHORT  RECS) 

* 

LONGP-A, 

(TRUNC,  FOLD,  ALLOW;  L  PAGES) 

* 

SHORTP-D. 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

INONLY-N, 

(YES,  NO) 

* 

CLASS>^. 

(TEXT,  BINARY) 

* 

UfGKEY-8. 

(NOT  IN  THE  DA  SENSE) 

* 

TmNG-72, 

TEXT  LENGTH  RANGE 

* 

OIHl-FORBIO. 

DIMENSICMAL  PREFERENCES 

* 

DIH2-PERMIT, 

* 

DIH3«(ASK,1), 

0IH4-(ASK,2) 

* 

GFT-360-CHS2H-S0URCE , 

* 

RECFM-FB, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECL^O, 

(80,  121,  137,  ETC.) 

* 

BLKSIZE«(80,4000), 

((MIN,  MAX)  OR  FIXED) 

* 

SPACE«(005,01) 

f 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CHPFAC-40. 

(EST  IL/DISK  BYTES  *  100) 

* 

DIH-2, 

(NATIVE  DIMENSION) 

* 

UOY, 

FORCE  UC:  (YES,  NO) 

* 

KEYHDL-B, 

(REQ,  GEN,  BLANK,  NO) 

* 

LONGR-F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

* 

8HOR71t«P, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

LONGP-A, 

(TRUNC,  FOLD.  ALLOW;  L  PAGES) 

* 

SH(ffiTP-D, 

(PAD,  D(WT  PAD;  SHORT  RECS) 

* 

INONLY-N, 

(YES.  NO) 

* 

CLASSY, 

(TEXT,  BINARY) 

* 

OIMl-FORBIO, 

OIMQiSIONAL  PREFERENCES 

* 

DIH2-PERHIT. 

* 

DIH3-(ASX.l), 

DIH4«(ASK,2), 

* 

KOFFS-O, 

(1) 

(1-ORG,  IN  TEXT  FIELD  ONLY) 

4r 

FOLOH6N-7. 

(1) 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

LNGKEY-0, 

(6) 

(NOT  IN  THE  DA  SENSE) 

* 

TXTLNG-80 

(74) 

TEXT  LENGTH  RANGE 
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GFT-360 -PLM80 -SOURCE ,  * 

RECFM-FB,  (FB,  VBA,  ETC.  ETC.)  * 

LRECL-80,  (80,  121,  137,  ETC.)  * 

BLKSIZE«(80,4000).  ((MIN,  MAX)  OR  FIXED)  * 

SPACE>(00S,01).  (PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAC-40,  (EST  IL/DISK  BYTES  *  100)  * 

KOFFS*73,  (1-ORG,  IN  TEXT  FIELD  ONLY)  * 

FOLDMGN-1,  (1  ORG,  IN  TEXT  FIELD  ONLY)  * 

DIM-2,  (NATIVE  DIMENSION)  * 

UC-Y,  FORCE  UC:  (YES,  NO)  * 

KEYHDL-B,  (REQ,  GEN,  BLANK,  NO)  * 

LONGl^F,  (TRUNCATE,  FOLD;  LONG  RECS)  * 

SHORTR-P,  (PAD,  DON'T  PAD;  SHORT  RECS)  * 

LONGP-A,  (TRUNC,  FOLD,  ALLOW;  L  PAGES)  * 

SHORTP-D,  (PAD,  DON'T  PAD;  SHORT  RECS)  * 

INONLY-N,  (YES,  NO)  * 

CLASS-T,  (TEXT,  BINARY)  * 

LNGKEY-8,  (NOT  IN  THE  DA  SENSE)  * 

TXrLNG«72,  TEXT  LENGTH  RANGE  * 

DIMl-FORBID,  DIMENSIONAL  PREFERENCES  * 

DIN2-PERMIT,  * 

DIM3«(ASK,1),  * 

DIM4«(ASK,2) 

GFT>360-SPPCOBOL-SOURCE,  * 

RECFM-FB,  (FB,  VBA,  ETC.  ETC.)  * 

LRECL-80,  (80,  121,  137,  ETC.)  * 

BIJCSIZE-(80,4000),  ((MIN,  MAX)  OR  FIXED)  * 

SPACE-(005,01),  (PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAC-40,  (EST  IL/DISK  BYTES  *  100)  * 

KOFFS-1,  (1-ORG,  IN  TEXT  FIELD  ONLY)  * 

FOLDMGN-6,  (1  ORG,  IN  TEXT  FIELD  ONLY)  * 

DIM-2,  (NATIVE  DIMENSION)  * 

UC-Y,  FORCE  UC;  (YES,  NO)  * 

XEYHDL^,  (REQ,  GEN,  BLANK,  NO)  * 

L0N6R-F,  (TRUNCATE,  FOLD;  LONG  RECS)  * 

SHORTR-P,  (PAD,  DON'T  PAD;  SHORT  RECS)  * 

LONGP-A,  (TRUNC,  FOU),  ALLOW;  L  PAGES)  * 

SHORTP-D,  (PAD,  DW'T  PAD;  SHORT  RECS)  * 

INONLY-N,  (YES,  NO)  * 

CLASS>rr,  (TEXT,  BINARY)  * 

LN6KEY-6,  (NOT  IN  THE  DA  SENSE)  * 

TXrLNG-74,  TEXT  LENGTH  RANGE  * 

DIMl-FORBID,  DIMENSIONAL  PREFERENCES  * 

DIM2-PERMIT,  * 

DIM3-(ASK,1),  * 

DIM4-(ASK,2) 
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(aT-360-CHS2H-OBJ, 

* 

RECFtNVBS, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECL-3516, 

(80,  121,  137,  ETC.) 

* 

BLKSIZE«(3520.3520), 

((MIN,  MAX)  OR  FIXED) 

* 

SPACE»(20,40), 

(PRIMARY,  SECONDARY.  DIRECTORY)* 

CMPFAO40, 

(EST  IL/DISK  BYTES  *  100) 

* 

F0Ll»«a<]»l. 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

DIH-2, 

(NATIVE  DIMENSION) 

* 

0C«N, 

FORCE  UC:  (YES,  NO) 

* 

L0NGR«F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

* 

SHORTRsp. 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

LONGPaA, 

(TRUNC,  FOLD,  ALLOtf;  L  PAGES) 

* 

SHORTPsD. 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

INONLY^. 

(YES,  NO) 

* 

CLASSaB, 

(TEXT,  BINARY) 

* 

KPFILL-Y, 

(TRAIL  FILLS  ARE  SIGNIF;  Y,  N) 

* 

SUPRXL-Y, 

(PERFORM  CODE  TRANS;  Y,  N) 

* 

IKGKEYaO. 

(NOT  IN  THE  DA  SENSE) 

* 

TmNG«3S12, 

TEXT  LENGTH  RANGE 

* 

OIMl-FORBID, 

DIMENSIONAL  PREFERENCES 

* 

DIM2«PERHIT. 

* 

0IM3«(ASK,1), 

0IM4>(ASK,2) 

* 

GFT^360-PLM80-0BJ, 

* 

RECFtt-FBA, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECI^133, 

(80,  121,  137,  ETC.) 

* 

BLKSIZE«( 133, 3500), 

((MIN,  MAX)  OR  FIXED) 

* 

SPACE«(20,40), 

(PRIMARY.  SECONDARY,  DIRECTORY)* 

CMPFAO40, 

(EST  IL/DISK  BYTES  *  100) 

* 

FOUHfGN*!, 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

DIN>3, 

(NATIVE  DIMENSION) 

* 

UC-N, 

FORCE  UC:  (YES,  NO) 

* 

LONGR«F. 

(TRUNCATE.  FOLD;  LONG  RECS) 

* 

SHORTRap, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

LONGP-A, 

(TRUIR:,  fold,  ALLOV;  L  PAGES) 

* 

SHORTPaD, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

INONLYaN, 

(YES,  NO) 

* 

CLASS-T, 

(TEXT,  BINARY) 

* 

KPFILI^Y, 

(TRAIL  FILLS  ARE  SIGNIF;  Y,  N) 

* 

SUPRXL-Y, 

(PERFORM  CODE  TRANS;  Y,  N) 

* 

LNGKEY-O, 

(NOT  IN  THE  DA  SENSE) 

* 

TXTLMG-133, 

TEXT  LENGTH  RANGE 

* 

DIMl-FORBID, 

DIMENSIONAL  PREFERENCES 

* 

DIM2aPERMIT, 

* 

DIN3apERNIT. 

DIM4-(ASK,2) 

* 
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GFTS360-ASH80-0BJ, 

* 

RECFM-FB, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECL-132, 

(80,  121,  137,  ETC.) 

* 

BLKSIZE>( 132, 3500), 

((MIN,  MAX)  OR  FIXED) 

* 

SPACE>(20,40). 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CHPFAC»40, 

(EST  IL/DISK  BYTES  *  100) 

* 

F0LDHGN»1, 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

DIM-2, 

(NATIVE  DIMENSION) 

* 

UON, 

FORCE  UC:  (YES,  NO) 

* 

LONGR-F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

* 

SHORTR-P, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

LONGP-A, 

(TRUNC,  FOLD,  ALLOW;  L  PAGES) 

* 

SH0RTP4, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

CLASSY, 

(TEXT,  BINARY) 

* 

KPFILL-Y, 

(TRAIL  FILLS  ARE  SIGNIF;  Y,  N) 

* 

SUPRXL-Y, 

(PERFORM  CODE  TRANS;  Y,  N) 

* 

LNGKEY-0, 

(NOT  IN  THE  DA  SENSE) 

* 

TmNG-133, 

TEXT  LENGTH  RANGE 

* 

INCXILY’^, 

(YES,  NO) 

* 

DIMl-FORBID, 

DIMENSIONAL  PREFERENCES 

* 

0IM2-PERMIT, 

* 

DIM3«(ASK,1), 

* 

DIM4-(ASK,2) 

GFT^360-JCL, 

* 

RECFH-FB, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECL-80, 

(80,  121,  137,  ETC.) 

* 

BLKSIZE«(80,4000), 

((MIN,  MAX)  OR  FIXED) 

SPACE«(005,01), 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CNPFAC-40, 

(EST  IL/DISK  BYTES  *  100) 

* 

KOFFS-73, 

(1-0R6,  IN  TEXT  FIELD  ONLY) 

* 

FOLDMGN-16, 

(1  ORG,  IN  TEXT  FIELD  ONLY) 

* 

DIM-2, 

(NATIVE  DIMENSION) 

* 

UOY, 

FORCE  UC:  (YES,  NO) 

* 

KEYHDL-G, 

(REQ,  GEN,  BLANK,  NO) 

e 

LONGR-F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

* 

SHORTR-P, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

LONGP-A, 

(TRUNC,  FOLD,  ALLOW;  L  PAGES) 

* 

SHORTP-D, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

INONLY-N, 

(YES,  NO) 

* 

CLASSY, 

(TEXT,  BINARY) 

* 

LNGKEY-8, 

(NOT  IN  THE  DA  SENSE) 

* 

1X11116-72, 

TEXT  LENGTH  RANGE 

* 

DIMl-FORBID, 

DIMENSIONAL  PREFERENCES 

* 

DIM2-PERMIT, 

* 

DIM3-(ASK,1), 

DIM4-(ASK,2) 

* 
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GFP«360-TEXT, 

* 

RECFtt>VB, 

(FB,  VBA,  ETC.  ETC.) 

* 

LRECIF136, 

(80,  121,  137,  ETC.) 

* 

BLRSIZEs( 140, 4000), 

((MIN,  MAX)  OR  FIXED) 

* 

SPACE«(010,02), 

(PRIMARY,  SECONDARY,  DIRECTORY)* 

CMPFAC=50, 

(EST  IL/DISK  BYTES  *  100) 

* 

K0FFS=0, 

(1-ORG,  IN  TEXT  FIELD  ONLY) 

* 

FOLDMGN^l, 

(1  ORG,  IN  TEXT  FIELD  (M«.Y) 

* 

011^2, 

(NATIVE  DIMENSION) 

* 

UC>^, 

FORCE  UC:  (YES,  NO) 

★ 

KEYHDL^N, 

(REQ,  GEN,  BLANK,  NO) 

* 

LONGR-F, 

(TRUNCATE,  FOLD;  LONG  RECS) 

* 

SH0RTR«P, 

(PAD,  DON’T  PAD;  SHORT  RECS) 

* 

L0NGP=F, 

(TRUIC,  FOLD,  ALLOW;  L  PAGES) 

* 

SH0RTP=D, 

(PAD,  DON'T  PAD;  SHORT  RECS) 

* 

IN0NLY>N, 

(YES,  NO) 

CLASSY, 

(TEXT,  BINARY) 

* 

LNGKEY^O, 

(NOT  IN  THE  DA  SENSE) 

* 

TXTUJG=(  1,132), 

TEXT  LENGTH  RANGE 

* 

DIH1«F0RBID, 

DIMENSIONAL  PREFERENCES 

* 

DIM2«(PERMIT,1), 

* 

DIM3s(PERMIT,2), 

DIM4«(ASK,3) 

* 
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4.  PART  IV:  UCLA  RECCOMMENDATIONS  ON  LIBRARIES  IN  NSW 


4,1.  THE  SPECIFIC  PROBLEM 


4.1.1.  IBM  TOOLS  IN  NSW 

If  NSW  is  to  provide  an  environment  for  the  installation  of  software 
tools  written  for  a  specific  family  of  computer  systems,  it  must 
provide  an  interface  between  th-  *5  tools  and  the  NSW  filespace. 
Specifically,  it  must  provide  a  mapping  between  file  constructs  that 
are  used  by  the  tools  and  those  that  can  be  provided  by  the  NSW 
encapsulating  foreman  as  implemented  for  that  system  family.  If 
such  a  mapping  is  difficult  to  define,  it  may  be  that  the  NSW 
filespace  design  should  be  embellished  accordingly. 

If  NSW  is  to  support  the  large  number  of  tools  that  have  been 
written  for  the  popular  IBM  System/360-370  family,  it  must  provide  a 
mapping  between  the  NSW  filespace  and  the  IBM  Basic  Partitioned 
Access  Method,  or  BPAM,  since  operation  of  almost  all  language 
processors  written  for  these  systems  depends  heavily  on  BPAM's  use. 

BPAM  is  an  IBM  program's  interface  to  the  IBM  Partitioned  Data  Set 
(PDS)  construct.  The  PDS,  in  turn,  is  IBM's  implementation  of  the 
notion  of  a  file  library.  There  is  no  similar  notion  in  the  current 
specifications  of  the  NSW  filespace. 
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4.1.2.  FILE  LIBRARIES 

Logically,  a  library  is  a  data  construct  which  defines  a  search 
sc<^.  The  objects  being  searched  for  carry  names  in  a  namespace 
internal  to  the  library.  This  namespace  may  be  private  to  the 
library  and  its  users,  and  independent  of  the  namespace  within  which 
the  library  itself  is  named,  or  it  may  be  a  private  subspace  of  the 
larger  namespace.  Library  files  of  some  form  have  been  with  us 
since  there  were  linking  loaders.  Most  major  computer  language 
definitions  include  specification  of  some  form  of  library  facility. 
This  is  true  of  COBOL,  of  PL/I,  and  of  macro-assemblers  as  a  class. 
A  library  facility  is  a  part  of  the  DOD  published  requirements  for 
ADA  (nee  DOD-l),  as  is  the  ability  to  structure  that  library  along 
application,  project,  and  user  lines. 

A  library  is  like  a  file  in  that  the  library  name  is  a  name  in  the 
host  operating  system's  file  name  space,  and  is  what  becomes  bound 
to  a  program's  file  by  the  operating  system's  file-management 
facilities  when  the  program  intends  to  use  that  file  as  a  search 
scope.  In  this  case,  the  internal  namespace  is  not  known  to  the 
file-management  system,  and  is  fully  managed  by  the  program. 

A  library  is  like  a  collection  of  files  in  that  thp  name  formed  by 
qualifying  a  name  from  its  internal  namespace  by  its  file  name  is 
itself  a  legitimate  file  name,  and  can  be  bound  to  a  program's  file 
iriien  that  program  intends  to  use  that  file  as  a  sequential  input 
source. 

A  library  can  thiis  serve  as  a  convenient  repository  for  a  general 
collection  of  like  files.  This  usage  is  an  inessential  side  effect; 
however,  it  points  out  that,  where  a  filespace  is  hierarchically 
structured,  there  is  great  similarity  between  a  library  and  a 
filespace  subtree. 


Supporting  the  IBM  File  System  in  NSW 
November  20,  1980  —  Part  IV:  Libraries 

PAGE  3 


4.1.3.  THE  IBM  IMPLEMENTATION 


4. 1.3.1.  DESCRIPTKM 


There  are  several  operating  systems  for  the  IBM  System/360-370 
family,  but  NSW  will  probably  be  concerned  with  two:  MVT,  a 
real-memory  system,  and  MVS,  a  virtual -memory  system.  In  both 
systems,  a  library  is  structured  as  a  PDS.  This  structure  has 
been  a  part  of  IBM  systems  since  OS/360  was  announced  in  1964.  In 
current  systems,  PDS's  are  not  only  supported,  they  are  required, 
as  is  illustrated  by  the  fact  that  one  of  the  supervisor's  basic 
services,  program  fetch,  demands  a  PDS. 

It  is  a  good  guess  that  future  IBM  system  announcements  will 
continue  to  require  PDS's,  and  it  is  a  certainty  that  they  will 
continue  to  support  them.  At  any  rate,  should  IBM  ever  cease  PDS 
support,  systems  using  PDS's  will  still  be  in  the  field  for  some 
years  thereafter. 

A  PDS  is  a  collection  of  named  files  of  like  type,  structure,  and 
function,  with  a  single  file  name,  and  a  single  disk  allocation 
and  attribute  set.  Each  "member"  of  the  collection  has  a  simple 
name,  and  may  have  a  number  of  "aliases".  The  set  of  names  and 
aliases  are  tabulated  In  a  special  "member"  called  the 
"directory".  The  directory,  by  virtue  of  being  unnamed,  is  not 
normally  available  to  processing  program  directly. 

On  the  system  command  level  (JCL  or  TSO),  a  reference  to  a  PDS  can 
nasM  either  the  collecti<»i  or  a  specific  "ommber"  of  the 
collection.  In  the  latter  case,  the  reference  is  to  a  sequential 
file  which  can  be  processed  as  such  by  almost  any  program  which 
uses  the  IBM  sequential  access  method  (SAM)  file  interface.  With 
some  unimportant  exceptions,  a  reference  to  the  PDS  as  a 
collection  can  only  be  processed  by  a  program  which  consciously 
uses  the  BPAM  interface,  that  is,  one  which  operates  on  a  library. 

A  PDS  as  a  library  is  indicated  whenever  a  program  is  to  be  told 
"whenever  you  need  to  locate  a  named  piece  of  data  of  this  certain 
sort,  search  this  subset  of  the  file  space."  This  is  particularly 
true  when  the  name  of  the  piece  of  data  cannot  be  known  until 
execution  time.  Common  applications  include:  a  command  language 
executor  searches  a  command  library  for  the  program  named  the  same 
as  the  command  just  entered;  a  linking  loader  searches  a 
subroutine  library  for  routines  whose  names  match  the  unresolved 
subroutine  references  within  a  program;  an  assembler  searches  a 
macro-definition  library  whenever  an  otherwise  undefined  operation 
code  is  encountered;  the  PL/I  compiler  searches  a  text  library 
whenever  a  "%INCLUDE"  statement  is  processed. 
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IBM  files  are  allocated  in  terms  of  contiguous  extents  of  real 
disk  space.  VThen  a  member  is  replaced  in  a  PDS,  its  space  is  not 
reused.  This  is  nicely  compatible  with  the  notion  of  version 
numbers  for  members,  since  under  that  notion  the  old  member  is  not 
to  be  destroyed  in  any  case;  however,  it  does  mean  that  space  must 
be  garbage  collected  on  occasion.  To  the  local  user,  the  garbage 
collection  problem  appears  only  as  the  necessity  to  run  an 
occasional  ^compress"  utility  on  the  library.  This  is  either  done 
whenever  the  user  feels  it  may  be  needed,  or  when  an  attempt  to 
add  a  member  fails.  When  the  "user"  is  a  file  package,  more 
concrete  criteria  will  have  to  be  defined.  This  is  essentially  a 
local  file  package  Implementor's  problem. 

4. 1.3.2.  TYPICAL  USAGE 

Meaningful  use  of  a  library  facility  requires  a  "concatenation" 
facility,  that  is,  a  method  to  allocate  an  ordered  set  of 
libraries  to  a  program  in  order  to  define  a  search  rule.  NSW 
support  for  concatenated  allocation  is  not  now  provided,  but  it 
will  not  be  difficult,  and  it  need  not  be  discussed  here. 

The  nu^er  of  members  and  volusw  of  data  in  a  PDS  vary  drastically 
according  to  the  application.  As  an  example  of  typical  data 
volumes,  consider  the  concatenation  of  PDS's  that  is  routinely 
allocated  to  the  OS/360  assembler's  macro  library  file  in  order  to 
asseodtle  a  file  package  routine: 


IBM  macro  library: 
UCLA  macro  library: 
NSW  macro  library: 
FLPK6  macro  library: 


TOTALS: 


313  members,  4.0  MB 
812  members,  4.9  MB 
23  members,  115  KB 

58  members,  524  KB 


1206  MEMBERS,  9.5  MB 


A  typical  file  package  assembly  will  actually  select  and  read 
perhaps  100  kilobytes,  or  about  a  dozen  members  of  this  data. 
Notice  that  not  only  is  a  rich  variety  of  macro  definitions  made 
available  to  the  programmer,  but  a  search  rule  is  specified  by  the 
order  of  concatenation.  The  user  must  be  given  control  of  his 
search  order,  so  he  must  be  able  to  specify  an  ordered  set  of  NSW 
file  names  to  be  provided  to  a  tool. 

This  presents  a  new  naming  problem.  If  the  tool  user  is  be  able 
to  name  the  IBM-provided  macro  library  at  UCLA,  then  that  library 
must  have  an  NSW  file  name.  However,  the  local  name  of  that 
library  is  fixed,  and  cannot  be  chosen  by  the  file  package  in  the 
same  way  that  a  true  NSW  file  name  is.  Therefore,  a  mechanism 


must  be  provided  for  assigning  an  existing  local  name  to  a  new  NSW 


.  I',  #  v/ 
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file  name.  A  slightly  expanded  version  of  FP-IMP  could  do  this. 

A  consequence  of  the  dual  nature  of  PDS  access  is  that  a  PDS  may 
be  used,  at  the  programmer's  discretion,  to  hold  any  collection  of 
similar,  related  files,  whether  or  not  they  are  ever  to  be 
accessed  as  a  library,  and  to  reference  and  operate  upon  them 
collectively. 

4. 1.3.3.  MISCELLANEOUS  PROBLEMS 

Other  problems  arise  when  one  tries  to  address  PDS's  and  their 
members  via  NSW.  Some  of  these  include: 

*  Version  numbers  need  to  be  provided  for  members  instead  of  for 
libraries. 

*  Member  names  may  need  to  be  both  mapped  and  unmapped  in  the 
NSW  file  name  space. 

*  Access  to  a  PDS  member  can  make  the  entire  library  appear  busy 
to  the  host  operating  system. 

*  Physical  copies  of  the  same  NSW  file  must  be  capable  of 
existing  both  as  sequential  files  and  as  members  of  PDS's. 

*  True  encapsulation  of  BPAM  presents  political  difficulties 
that  may  make  it  Impractical. 

*  Alias  management  will  surely  cause  complications  somewhere. 
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4.1.4.  DE8IOEBATA 

Ne  feel  that  the  absence  of  any  form  of  library  support  in  NSW  is  a 
serious  omission.  The  entire  NSW  community  could  benefit  from  the 
integration  of  the  library  concept  directly  into  the  NSW  file 
structure.  Direct  benefits  could  include: 

*  IBM  tools  could  be  supported. 

*  The  IBM  library  li^leaeatatioa  could  be  enriched  by  merging  in 
good  NSW  concepts  like  version  numbers  for  members.  (Note  that 
NSW  file  version  nu^ier  siipport  is  being  Implemented  in  NSW.) 

*  A  mechanism  for  defining  search  scopes  in  NSW  would  be  provided. 
This  would  be  especially  Iqwrtant  for  "new"  (unencapsulated) 
tools  on  non- IBM  hosts. 

*  A  convenient  and  efficient  form  of  collective  file  operations 
would  becosM  available  to  NSW  users. 

*  Installation-provided  and  maintained  libraries  could  be  shared 
with  NSW  users. 


■■ 
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4.2.  THE  PROBLEM  IN  PERSPECTIVE 


4.2.1.  THE  GENERAL  PROBLEM  OF  UNMOVEABLE  FILES 

The  library  problem  in  NSW  is  related  to  the  general  problem  of 
NSW'oamoveable  file  types.  These  include  all  non-sequential  types, 
such  as  those  processed  by  IBM's  Basic  Direct  Access  Method  (BDAM), 
Indexed  Sequential  Access  Method  (ISAM),  or  Virtual  Storage  Access 
Method  (VSAM).  They  include  files  with  an  affinity  to  a  particular 
tool,  host,  or  operating  system,  as  a  database  has  affinity  to  a 
DBMS  implementation.  They  also  include  files  which,  by  virtue  of 
their  great  mass,  are  not  practically  moveable.  If  a  library  is 
represented  as  a  file,  it  is  usually  unmoveable  due  to  its  great 
mass.  If  it  is  represented  as  a  PDS,  it  is  also  unmoveable,  except 
for  "family  copies",  due  to  its  non-sequential  nature  and  its 
affinity  for  an  operating  system. 

It  is  likely  that  most  unmoveable  files  will  be  integrated  into  NSW 
through  a  simplistic  model  in  which  the  construct  is  given  an  NSW 
name,  perhaps  even  an  NSW  file  name,  but  it  is  operated  on  only  by 
tool  code,  never  by  NSW  code  per  se. 

4.2.2.  THE  ONERAL  PROBLEM  OF  COLLECTIVE  FILES 

The  library  problem  is  also  related  to  the  general  problem  of 
collective  file  types.  These  also  include  "stacked  tapes”. 
"Stacked  tapes”  will  be  important  in  NSW  because  they  frequently 
will  be  the  eiqxirted  results  when  NSW  is  used  for  cross-system 
program  development  for  systems  such  as  the  UYK-20.  They  consist  of 
a  sequence  of  sequential  files,  any  of  which  could  be  processed  as  a 
legitimate  NSW  file.  Once  "stacked"  as  a  "load  tape"  image,  these 
will  be  collectively  known  by  one  NSW  file  name,  and  that  collective 
file  must  be  transmittable  by  the  NSW  to  a  host  capable  of  writing  a 
UTK-20  load  tape.  The  NSW  file  package's  "IL"  data  representation 
has  been  given  a  special  "end-of-subfile"  construct  to  accomodate 
this  transmission,  although  it  is  not  yet  being  used.  While  this 
usage  does  not  require  that  the  individual  members  of  the  "stack"  be 
ittdependmtly  retrievable  and  replaceable,  that  usage  could  develop. 
In  either  case,  it  is  highly  probable  that  we  will  represent  a 
"stacked  tape"  on  the  IBM  system  as  a  PDS. 

Another  type  of  collective  file  that  will  see  use  in  NSW  is  the 
"mall  file”  of  the  TENEX  sort.  A  mail  file  is  really  a  special  use 
of  a  library  file,  and  an  IBM  implementation  could  well  use  a  PDS. 
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4.3. 


PROPOSED  SOLUTIONS 


4.3.1.  THE  DATABASE  MODEL 

4.3. 1.1.  DESCRIPTION 

In  this  model,  a  PDS  is  considered  to  be  a  special  form  of 
database  it  has  an  NSV  file  name,  but  not  an  NSW  file 
structure.  Its  NSW  file  name  can  be  allocated  to  any  batch  or 
interactive  tool,  provided  that  tool  resides  on  the  same  host  as 
the  single  physical  copy  of  the  file.  The  IBM  file  package  will 
never  make  a  tool  copy  of  such  a  file,  but  will  always  grant  the 
tool  access  to  the  NSW  copy  directly  (this  mechanism  is  already 
implesMnted  in  the  IBM  file  package).  Thus  encapsulated  tools  can 
access  such  a  file  in  native  mode;  however,  explicit  tools  must  be 
provided  for  file  maintenance. 

In  the  general  database  model,  file  structure  and  implementation 
are  dictated  by  a  tool  or  set  of  tools,  and  laaintenance  functions 
are  Included  in  that  set,  since  the  set  of  meaningful  maintenance 
functions  depends  on  the  file  structure  and  implementation.  In 
the  case  of  PDS  maintenance,  the  following  probably  represents  a 
minimal  set  of  maintenance  functions  to  be  provided  by  a  special 
tool  or  tools: 

1)  Create  a  PDS. 

2)  Copy  an  NSW  file  into  a  PDS  member. 

3)  Copy  a  PDS  member  into  an  NSW  file. 

4)  List  the  member  and  alias  names. 

5)  Delete  a  member  or  alias. 

6)  Rename  a  member  or  alias. 

7)  Assign  an  alias  to  a  member. 

8)  Analyze  a  PDS  for  garbage  content. 

9)  Compress  (garbage  collect)  the  PDS. 

This  model  would  enable  any  IBM  tool  to  process  a  PDS  as  a 
library,  but  not  to  process  a  member  as  a  sequential  file,  since 
the  member  has  no  NSW  file  name.  However,  any  NSW  tool,  IBM  or 
otherwise,  could  operate  on  a  member's  data  if  the  user  made 
explicit  use  of  the  maintenance  tools  to  extract  and  replace  it. 
Specific  IBM  tools  could  regain  their  ability  to  operate  on  a  PDS 
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■ember  by  using  a  local  NSW-provided  preface  routine,  such  as  the 
UCLA  Encapsulator  Comnand  Interpreter  (ECI)  to  explicitly  refine 
the  PDS  allocation  into  a  Benber  allocation.  This  aechanisa  would 
be  supplied  initially  to  the  IBM  TSO  EDIT  tool,  since  it  accounts 
for  the  great  majority  of  sequential  references  to  PDS  aeabers. 

In  order  to  bring  a  PDS  unchanged  into  NSV,  a  special  version  of 
IMPORT  would  be  required.  This  version  must  support  assigning  an 
NSV  file  name  to  a  given  existing  file  which  NSV  will  share  with 
non-NSV  users  of  the  host. 

EVALUATION 

The  database  model  is  simple  and  easy  to  implement;  however,  it 
fills  only  one  NSV  desideratum.  It  makes  it  possible  to  integrate 
IBM  tools  into  NSV,  but  at  the  expense  of  using  non-NSV  methods 
and  mechanisms  to  do  a  large  part  of  the  kinds  of  processing 
usually  associated  with  program  developoient  tasks.  It  does  not 
iaq>rove  upon  the  library  functions  available  from  the  IBM 
implementation,  nor  does  it  provide  search  scopes  and  collective 
operations  to  non-IBM  tools  or  to  NSV  users.  It  makes  library 
data  available  for  general  use  only  through  special  user  action. 
It  violates  a  fundamental  NSV  precept  by  allowing  a  tool  write 
access  to  the  NSV  copy  of  a  file. 

Nevertheless,  the  database  model  has  one  overpowering  advantage  — 
it  can  be  implemented  by  host  software  development  personnel 
without  requiring  any  changes  at  all  to  the  works  manager  or  to 
other  NSV  code.  The  probable  result  of  this  fact  is  that, 
whatever  model  is  selected  for  integrating  libraries  into  NSV 
properly,  the  database  model  is  going  to  be  used  in  the  interim  to 
support  existing  needs.  Such  interim  support  will  be  fully 
sufficient  for  existing  tools  and  for  those  plaxmed  for  the 
immersion  project  ("Immersion”  is  used  to  denote  the  adoption  of 
the  NSV  as  the  sole  or  prisiary  vehicle  for  the  development, 
maintenance,  and  configuration  of  the  NSV  itself). 
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4.3.2.  THE  NSW  SCOPE  MODEL 


4.3.2. 1.  DESCRIPTION 

This  BKxlel  is  based  upon  the  similarity  between  a  library  and  a 
subtree  of  a  hierarchically  structured  filespace.  NSW  has  such  a 
fllespace,  and  calls  such  a  subtree  a  scope.  The  scope  model 
hinges  on  these  features: 


*  NSW  must  allow  a  user  to  allocate  an  NSW  scope 
an  NSW  file  name  to  a  tool. 


name  instead  of 


*  BPAM  must  be  encapsulated  to  the  point  of  giving  control  to 
NSW  code  whenever  a  tool  issues  the  supervisor  service  call 
that  locates  members  within  a  PDS  (the  BLDL  SVC  call). 

*  The  NSW  IBM  encapsulating  foreman  must  form  filespecs  by 
qualifying  each  requested  member  naoie  by  the  allocated  scope 
name,  must  issue  WM~6ET  calls  against  these  filespecs,  and 
must  copy  any  resulting  files  into  a  true  PDS  in  the  tool's 
workspace,  under  the  appropriate  member  names. 

• 

*  The  information  flow  of  WM-GET  must  be  embellished  to 
communicate  from  the  foreman  to  the  file  package  the  name  of 
the  PDS  into  which  the  tool  copy  is  to  be  made. 

*  BPAM  must  also  be  encapsulated  to  the  point  of  giving  control 
to  NSW  code  whenever  a  tool  issues  the  supervisor  service  call 
that  creates  members  within  a  PDS  (the  STOW  SVC  call). 


•sf 


■  .f  t  ,*  I 


*  The  NSW  IBM  encapsulating  foresMn  must  retain  the  name  of  each 
newlycreated  member  in  its  UQ),  as  each  constitutes  a 
deliverable  file. 

*  The  NSW  user  interface,  or  at  least  the  IBS  component,  must  be 
sophisticated  to  manage  the  case  where  the  set  of  deliverables 
for  a  tool  instance  is  bound  after  tool  execution. 

4. 3. 2. 2.  EVALUATION 

The  scope  model  has  much  appeal.  It  integrates  IBM  tools  into 
NSW,  and  it  does  it  throng  the  encapsulation  technique  that  NSW 
prefers  for  such  purposes.  It  does  embellish  upon  the  PDS 
implementation  such  that  "members",  being  NSW  files,  can  have  all 
the  attrictive  NSW  properties,  like  version  numbers.  It  provides 
mechanisms  that  will  be  useful  to  "new"  tools  on  non-IBM  hosts. 


Ns:;'' 

«  i  I  ‘  ' 


Supporting  the  IBM  File  System  in  NSW 
Noveiii>er  20,  1980  —  Part  IV:  Libraries 

PAGE  11 


On  the  negative  side,  the  scope  otodel  can  be  expected  to  require 
an  order  of  magnitude  more  space  in  the  NSW  file  catalog,  since 
not  only  are  all  libraries  there,  but  each  "member"  is 
individually  represented  by  an  NSW  file  name.  This  model  does  not 
provide  more  efficient  collective  operations  on  libraries,  since 
NSW  file  operations  on  scopes  will  be  sliiq>le  iterations  of  file 
operations. 

Since  local  TBH  libraries  must  still  be  represented  as  POS's,  this 
model  can  only  handle  user  data.  This  will  prevent  the  user's 
specifying  a  search  order  between  public  and  private  libraries. 

But  the  crippling  disadvantages  of  the  scope  model  are  matters  of 
practicality  and  efficiency.  Such  an  implementation  is  not 
feasible  under  a  real-memory  batch-processing  system  such  as 
OS/360  MVT,  due  to  various  combinations  of  the  following  facts: 

*  All  network  I/O  for  a  real-memory  batch  Job  MUST  be  prestaged. 
Otherwise,  a  typical  two-minute  assembly  could  be  stretched  to 
half  an  hour,  with  one  batch  stream  and  perhaps  200K  of 
storage  tied  up  for  that  interval.  This  is  because  a  typical 
assembly  will  ask  for  a  dozen  macros,  one  at  a  time,  when  it 
decides  it  needs  them.  Each  would  be  a  WM-GET  request,  and 
could  take  several  minutes. 

*  It  is  not  sensible  to  prestage  an  entire  search  scope,  when 
only  a  very  small  percentage  of  the  data  will  actually  be  read 
by  the  tool. 

*  It  is  not  possible  to  predict  which  parts  of  a  search  scope 
will  be  needed. 

*  Even  if  the  entire  search  scope  could  be  coaxed  into  staying 
on  one  host,  the  encapsulation  of  the  elementary  supervisor 
services  used  by  IBM  tools  to  search  and  read  libraries  is  not 
politically  practical.  Without  system  modifications,  the 
search  scope  MUST  be  structured  as  a  concatenation  of 
Partitioned  Data  Sets.  The  modifications  to  the  IBM 
supervisor  to  make  this  not  so  are  not  likely  to  be  allowed  by 
any  systems  manager. 

It  may  be  that  some  of  these  problems  do  not  apply  to  MVS.  Under 
a  virtual -memory  sjrstem  it  may  be  practical  to  do  no  prestaging  of 
library  data  at  all,  since  waiting  for  a  WH-GET  will  not  tie  up 
valuable  hardware.  However,  remember  that  the  only  IBM 
installation  currently  in  NSW  is  an  MVT  batch  system,  and  that 
significant  numbers  of  such  systems  exist  in  DOD  installations. 
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Unfortunately,  neither  MVT  nor  MVS  provides  a  general  mechanism 
comparable  to  the  JSYS  traps  of  TENEX,  so  the  BLDL  and  STOtf 
routines  must  be  modified  in  order  to  encapsulate  those  BPAH 
functions.  Such  modifications  are  not  to  be  done  lightly,  as  they 
cause  a  loss  of  IBM  software  support,  so  that  many  IBM 
installations  would  not  consider  them.  Unlike  some  vendors,  IBM 
is  quite  unresponsive  to  requests  that  they  add  such  changes  as 
supported  features. 
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4.3.3.  THE  COLLECTIVE  FILE  MODEL  —  BASIC  FORM 


4.3.3. 1.  DESCRIPTION 

In  this  model,  the  NSW  filespace  is  embellished  to  include  the 
notion  of  a  file  library  construct,  but  not  the  notion  of  version 
numbers  for  library  members.  Library  representation  is  presumed 
to  be  host-family  specific,  so  each  host  family  is  allowed  to 
specify  its  own  implementation.  Libraries  thus  become  more  or 
less  unmoveable;  however,  library  members  can  move  freely. 

The  basic  collective  file  model  hinges  on  these  features: 

*  The  works  manager  is  aware  of  two  new  file  attributes, 
"library”  and  "member". 

*  NSW  must  allow  a  user  to  allocate  libraries  and  members,  as 
well  as  ordinary  NSW  files,  to  a  tool. 

*  An  NSW  file  with  the  "library"  attribute  is  always  so 
represented  in  the  NSW  file  catalog.  It  may  not  have  more 
than  one  physical  copy.  Otherwise,  it  is  treated  as  a  normal 
NSW  file.  There  are  some  file  operations  to  which  it  is  not  a 
legal  argument,  and  the  works  manager  could  do  some  error 
checking;  however,  actual  enforcement  of  any  such  restrictions 
will  be  the  file  package's  responsibility. 

*  An  NSW  file  acquires  the  library  attribute  when  it  is  Imported 
or  delivered  into  a  non-existent  NSW  file  name.  The  importing 
file  package  reports  the  attribute  to  the  works  manager,  who 
records  it. 

*  An  NSW  filename  or  filespec  is  recognized  to  have  the  member 
attribute  because  of  its  syntactic  form  --  it  consists  of  the 
qualification  of  a  simple  name  by  a  legitimate  NSW  filename  or 
filespec,  using  a  unique  qualification  syntax. 

*  The  NSW  member  name  is  the  same  as  the  local  member  name,  but 
the  library  name  is  mapped  as  for  any  NSW  file. 

*  A  "member"  file  is  represented  explicitly  in,  the  NSW  file 
catalog  if  and  only  if  there  is  one  or  more  physical  copies 
other  than  the  one  in  the  library  Itself.  The  works  manager 
will  assume  the  existence  of  a  member  not  so  represented  if 
the  qualifying  file  name  exists  and  has  the  library  attribute. 
The  file  package  has  final  responsibility  for  detecting  the 
non-existence  of  a  member  name. 
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*  When  a  member  is  exported  from  a  library  and  a  NSW  copy  is 
kept,  an  explicit  NSW  file  catalog  entry  is  made  for  the 
fully-qualified  member  name,  and  the  new  physical  copy  is 
entered  into  that  entry.  The  presence  of  the  member  attribute 
implies  the  existence  of  the  physical  copy  in  the  library 
Itself. 

*  When  there  is  an  entry  for  a  member,  it  is  implicitly  linked 
to  the  entry  for  its  library  through  name  similarity.  This 
link  can  be  found  through  existing  disambiguation  mechanisms. 

*  When  a  file  is  delivered  into  a  "member”  file,  the 

corresponding  library  must  already  exist,  and  delivery  must  be 
performed  by  the  file  package  at  that  site.  The  works  manager 
must  thus  route  the  file  package  call  accordingly. 

Presumably,  all  existing  file  package  implementations  have 
cross -network  Import  capability. 

*  In  general,  when  a  file  is  delivered  into  an  existing  version 
of  an  NSW  file,  all  physical  copies  of  that  file  must  be 
deleted.  Specifically,  when  delivery  is  to  a  member,  if  that 
member  name  is  explicitly  represented  in  the  file  catalog,  all 
its  non-PDS  physical  copies  are  scheduled  fpr  deletion,  and 
the  member  catalog  entry  is  deleted.  (The  PDS  copy  will  be 
deleted  by  the  "replace"  option  on  the  file  package  call.) 

*  All  file  package  calls  must  be  embellished  to  include  member 
names  where  appropriate.  It  will  probably  be  wise  to 
communicate  the  "library"  and  "member"  bits  somewhere  in  such 
calls,  although  the  file  package  may  be  able  to  discover  this 
for  itself. 

*  FP-IMP  must  be  able  to  report  the  library  attribute  in  its 
reply.  It  must  also  have  an  option  that  assigns  an  NSW  file 
name  to  an  existing  file  which  NSW  will  share  with  non-NSW 
users . 

*  When  WH-GET  is  issued  against  a  library  name,  the  file  package 

will  grant  access  directly  to  the  sixigle  NSW  copy.  The 
foreman  must  ensure  read-only  access.  A  request  for  write 

access  to  an  entire  library  will  be  denied  by  the  foreman. 

*  Delivery  into  an  existing  library  name  is  not  defined. 

*  A  request  to  delete  a  member  is  not  a  special  case,  except 
that  two  file  catalog  entries  may  be  involved. 

*  A  request  to  rename  a  member  must  change  only  its  member  name. 
This  request  must  be  passed  to  the  file  package,  as  member 
names  are  not  mapped  by  the  works  manager.  Thus  a  new  file 
package  call  must  be  defined. 
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4. 3. 3. 2. 


*  While  this  model  does  not  provide  versions  for  members,  a 
library,  being  an  NSW  file,  will  have  versions.  The  works 
oianager  must  recognize  that  delivery  into  a  member  does  not 
change  the  version  number  of  the  library  itself. 

*  For  the  IBM  implementation,  a  maintenance  tool  must  be 
provided  to  handle  at  least  these  chores: 

1)  Create  a  PDS. 

2)  Assign/delete  an  alias. 

3}  Analyze  a  PDS  for  garbage  content. 

4)  Compress  a  PDS. 

EVALUATION 

This  model  addresses  more  NSW  desiderata  than  those  previously 
described.  IBM  tools  can  be  supported,  and  they  can  access  PDS 
libraries  or  members  without  change.  Non-IBM  tools  can  access  PDS 
members.  A  search  scope  construct  is  defined,  and  can  be 
implemented  in  non-IBM  file  packages  as  well.  Such 
implementations  are  not  constrained  to  be  similar  to  PDS's. 
Collective  operations  on  libraries  are  possible.  Non-NSW 
libraries  can  be  named  and  used  by  NSW  users.  However,  the  PDS 
implementation  itself  is  not  embellished;  specifically,  version 
numbers  are  not  provided  for  mrabers. 

This  model  does  require  extensive  works  manager  modifications,  but 
they  are  all  straightforward.  Only  incremental  space  increases 
need  be  expected  in  the  file  catalog. 

PDS  garbage  collection  will  have  to  be  handled  manually  at  first. 
It  is  possible  that  this  can  be  automated  later,  but  it  is  not 
necessary  for  Implementation  of  the  siodel. 
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4.3.4.  THE  COLLECTIVE  FILE  MODEL  VITH  VERSIONS 


4.3.4. 1.  DESCRIPTION 

IHis  model  is  a  direct  extension  of  the  previous  one,  and  is  only 
treated  separately  to  avoid  excessive  descriptive  complication. 
Additional  features  include: 

*  The  vorks  manager  supports  version  numbers  on  simple  member 
names.  Version  numbers  may  still  exist  for  libraries,  since 
they  are  NSV  files,  but  they  have  less  meaning  now,  and  their 
use  should  probably  be  discouraged.  It  is  possible  that  the 
works  manager  should  specifically  forbid  version  numbers  for 
libraries. 

*  Member  names  are  now  mapped  in  a  special  way:  the  ’’current" 
version  of  a  member  has  the  same  NSV  name  and  local  name;  all 
other  versions  exist  in  the  same  library,  but  under  generated 

names. 

*  The  names  for  non-current  members  are  chosen  by  the  local  file 
package  in  the  same  way  that  it  chooses  ,  local  names  for 
ph]rslcal  ccqpies  of  any  NSV  file.  The  internal  namespace  has 
an  area  fenced  for  this  purpose. 

*  A  member  with  no  non-PDS  physical  copies  and  no  non-current 
versions  is  not  represented  in  the  NSV  file  catalog.  Non-PDS 
physical  copies  are  represented  as  in  the  basic  collective 
file  model. 

*  Non-PDS  physical  copies  of  a  non-current  version  are  not 
permitted.  Vhen  the  current  version  number  changes,  any 
non-PDS  copies  are  deleted. 

*  The  file  catalog  entry  for  a  member  includes  a  mapping  of 
version  numbers  and  generated  member  names  for  all  non-current 
versions.  This  list  can  have  an  NSV-wide  maximum  length 
be3rond  which  old  versions  are  deleted  automatically. 
Normally,  versions  are  deleted  manually. 

*  Vhen  both  the  version  number  list  and  the  physical  copy  list 
of  a  member  entry  in  the  file  catalog  become  empty,  the  entry 
is  deleted  from  the  catalog. 

*  Vhen  delivery  into  a  PDS  is  to  a  now  version  of  an  existing 
member,  the  file  package  must  be  told  this.  It  must  renasw 
the  old  version  to  a  generated  name,  store  the  new  version 
under  the  member  name,  and  report  to  the  works  manager  the  new 
name  of  the  old  version.  The  works  manager  must  record  this 
name  in  the  version  list  of  the  member’s  entry  in  the  file 
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catalog,  creating  such  an  entry  if  necessary. 


4. 3. 4. 2.  EVALUATION 


This  model  is  indeed  all  things  to  all  people.  It  fills  all  the 
library-related  NSW  desiderata,  and  significantly  enhances  the  IBM 
PDS  implementation.  However,  it  requires  even  more  code 
modification  than  the  basic  model. 

Techniques  for  controlling  version  number  growth  would  have  to  be 
explored  before  this  model  were  isiplemented.  Otherwise,  it  could 
cause  a  serious  explosion  in  the  file  catalog.  More  serious  for 
an  IBM  host  system,  PDS  space  could  grow  at  an  alarming  rate. 
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4.4.  RECOMMENDATIONS 

NSW  architects  should  consider  all  these  models,  along  with  hybrids  of 
them,  in  designing  a  library  facility  for  NSW.  The  feelings  of  the 
authors  are  these: 

*  Despite  Its  attractive  features,  the  NSW  scope  model  has 
unfortunate  deficiencies  that  make  its  isiplementation 
unattractive. 

*  The  database  model  should  be  implemented  at  UCLA  as  soon  as 
possible,  to  serve  the  needs  of  the  immersion  project  and  those  of 
existing  tools  like  MACR080. 

*  MCA  should  plan  an  implementation  based  on  the  basic  collective 
file  model,  and  should  try  to  have  it  ready  before  large  numbers 
of  users  have  to  learn  to  use  the  interim  database'model 
implementation. 

*  miA  should  specify  an  extension  to  its  implementation  based  on  the 
collective  file  model  with  versions;  however,  implementation  of 
this  extension  could  be  deferred  for  the  time  being. 

*  In  any  case,  the  notion  of  importing  non-NSW  files  for  shared  use 
should  be  supported  by  NSW.  Access  to  such  files  should  always  be 
read-only,  and  should  be  to  the  original,  non -NSW  copy. 
Maintenance  ahould  be  outside  NSW.  This  notion  can  be  implemented 
and  si^ported  by  individual  file  packages;  however,  it  is  useful 
enough  to  deserve  a  uniform,  NSW-wide  specification. 


